Contributing to Baserock

Join the conversation

The baserock community members appreciate feedback, ideas, suggestion, bugs and documentation just as much as code. Please join us on #baserock on irc.freenode.net and our development list.

We maintain a list of ideas for things to do with Baserock.

Get a Baserock OpenID

You will need a Baserock OpenID if you want to submit changes to the Baserock software for review in gerrit. You can also use your Baserock OpenID to login to this site if you want to contribute to the wiki.

You can get a Baserock OpenID from openid.baserock.org

Note: it is possible to create multiple OpenIDs with the same email. Baserock's instance of StoryBoard, however, can only use one of these. If you're having issues logging in to StoryBoard, check that you're using the right one.

Set up a gerrit account

We use gerrit for tracking and reviewing changes to Baserock software (i.e. the projects stored in the baserock/* repos on git.baserock.org). If you would like to contribute any changes you will need set up an account at gerrit.baserock.org so that you can submit your changes. To setup your gerrit account, you will need an OpenID from openid.baserock.org.

The following steps can be done on your host machine.

  1. Register in gerrit.baserock.org - use the Sign In button at the top right
  2. Go to the settings page
  3. Set your 'Username'
  4. Upload your public ssh key
  5. Check it has succeeded by sshing to the 'Username' you set in 4

    ssh -p 29418 <Username>@gerrit.baserock.org

    If you have successfully added your key you should see the following

     ****    Welcome to Gerrit Code Review    ****
     Hi <your name>, you have successfully connected over SSH.
     Unfortunately, interactive shells are disabled.
     To clone a hosted Git repository, use:
     git clone ssh://<Username>@gerrit.baserock.org:29418/REPOSITORY_NAME.git
     Connection to gerrit.baserock.org closed.
    

Developing your change

You develop your change in your development VM.

Changing morph

To contribute a change to morph. do the following:

  1. Follow the steps in Using latest version of Morph, (cloning from gerrit.baserock.org rather than git.baserock.org)

    git clone ssh://<Username>@gerrit.baserock.org:29418/baserock/baserock/morph --origin=gerrit

    (The --origin=gerrit option will be useful when 'git-review' is available in Baserock as 'git-review' knows about the 'gerrit' remote.)

  2. Get the commit-msg hook that is needed to automatically generate the Change-Id's that gerrit needs :

    scp -p -P 29418 <Username>@gerrit.baserock.org:hooks/commit-msg morph/.git/hooks/

    To find this, navigate to gerrit.baserock.org -> Projects -> List (in the top left), then scroll down to baserock/baserock/morph. Click the 'clone with commit message hook' and 'SSH' buttons (under Project/baserock/baserock/morph). Copy the command displayed just below it into your VM (removing the stuff before 'scp -p')). If there is no 'SSH' button displayed, you need to sign in (top right).

  3. Create a branch and hack on morph

     cd morph/
     git checkout -b my-topic-branch
     ... #do some stuff`
    
  4. Commit your changes

  5. Run the Morph test suite

     cd /path/to/repo/morph
     # When running into memory issues use `TMPDIR=/src/tmp ./check`
     ./check
    
  6. Rebase your commits if necessary - see below

  7. When all the tests pass, and your change is ready to be reviewed, push the branch to gerrit for review:

    git push gerrit HEAD:refs/for/master/my-topic-branch

Changing systems defined in definitions.git

To change these systems, follow these steps

    # Clone the definitions repository (if you haven't already done so)
    git clone git://git.baserock.org/baserock/baserock/definitions

    # Add gerrit as a remote
    cd definitions/
    git remote add gerrit ssh://<Username>@gerrit.baserock.org:29418/baserock/baserock/definitions

    # Get the commit-msg hook that generates the Change-Id's that gerrit needs
    scp -p -P 29418 <Username>@gerrit.baserock.org:hooks/commit-msg .git/hooks/

    # Make and commit the changes to the definitions files
    ...

Build, deploy and test the changes systems as described in the Simple build-deploy workflow, until you are happy with your changes

Rebase your commits if necessary - see below

When all the tests pass, and your change is ready to be reviewed, push the branch to gerrit for review:

 git push gerrit HEAD:refs/for/master/my-topic-branch

Unpack failed error when pushing changes

If you see this error when you push your changes,

git push gerrit HEAD:refs/for/master/my-topic-branch Counting objects: 1, done. Writing objects: 100% (1/1), 263 bytes | 0 bytes/s, done. Total 1 (delta 0), reused 0 (delta 0) error: unpack failed: error Missing tree 337dc3b05e50bea244c8fc6c6bb7d82ddcab55dd fatal: Unpack error, check server log To ssh://yourusername@gerrit.baserock.org:29418/baserock/baserock/definitions ! [remote rejected] HEAD -> refs/for/master/my-topic-branch (n/a (unpacker error)) error: failed to push some refs to 'ssh://yourusername@gerrit.baserock.org:29418/baserock/baserock/definitions'

then use the --no-thin option as a workaround for this problem:

`git push --no-thin gerrit HEAD:refs/for/master/my-topic-branch`

Rebasing

(This section may need more work when we have more experience of working with gerrit. Particularly the section about making and resubmitting changes after review - use of the commit hook, and topic ids may make this easier)

Rebasing is always permissible for branches that meet the following requirements:

  1. The branch has not yet been merged into its target
  2. The branch has not been used as the basis for any other changes which have been merged into anywhere else.
  3. The act of rebasing will simplify or clarify the patches in the branch.

If during patch review, changes are required, then rebasing the branch will allow for those changes to be applied to the correct parts of the branch rather than on top afterwards.

Ideally, if you are being reviewed on the mailing list then always rebase in a separate branch, producing a new ref with a new name, deleting the old ref once you are satisfied with the rebase work. This approach means that the non-corrected patches are less likely to be accidentally merged by someone.

If you are being reviewed on gerrit, once you have rebased, push the changes in the same way as you previously did. You should keep the same Change-Id: but can change the rest of the commit log.

Patch series on Gerrit

You may find when submitting patch series to Gerrit, that patches relying on changes in previous commits in the series are labelled with 'Merge Conflict'. This is due to the conflicting patch relying on some changes earlier in the series, which are not yet merged. This is not a problem, as the patches should all be merged when the series gets merged. This is mostly a problem with Gerrit, and its lack of proper support for patch series.

Submitting bug reports

The Baserock team is always grateful to be told about issues. Baserock uses Storyboard to log bugs and suggestions. Please feel free to make a new story with your bug (though do check it hasn't been submitted already). Alternatively, you can use #baserock on irc.freenode.net or the development list to contact the team.

Submitting changes via the mailing list

Details of how to do this are here

You may want to do this

  • if gerrit is down or unavailable
  • if you are submitting changes to system components which are not Baserock software i.e. projects mirrored in the delta/* repos on git.baserock.org)
  • if you don't have the time or inclination to register for gerrit