Actions

Merging code to the trunk¶

Table of contents
Merging code to the trunk

For code to be added to a release version of MAUS it first needs to merged into the MAUS trunk. All code added to the trunk needs to be submitted via the Bazaar version control system (see the guide at Bazaar Usage).

Making a new feature branch¶

The preferred method for organising code development in MAUS with Bazaar is via feature branches, that is, each distinct job you wish to code should have its own development branch, forked from the MAUS trunk. This offers numerous advantages over having one large branch with multiple features being developed at the same time. These include making debugging problems far easier, and aiding with keeping responsibility between developers for each job well divided.

To make a new branch of the trunk do the following:

bzr branch lp:maus/merge my_feature_branch

Note that if you are developing a feature or fix which address an issue being tracked on the issue tracker, it is good practice to include the issue number in the branch name.

Build the new branch, and make an initial commit:

bzr commit -m 'Initial commit'

Push the code to a new branch on Launchpad:

bzr push lp:~my_launchpad_id/maus/my_feature_branch

The branch is now ready for you to develop in. Ensure you commit regularly as you go. When the feature development is complete, merge the latest changes from the trunk, and then ensure all the criteria listed below are met. Perform a final commit and push to Launchpad. Once done, your branch is ready to be proposed for merging to the trunk.

Code requirements¶

For a branch to be ready for merging to the trunk the following criteria need to be met.

Tests requirements¶

A personal branch on the Jenkins test server to check the tests represents best practice (if you need a test job on Jenkins contact the head of MAUS)
The branch must pass all the current MAUS tests - style, unit, integration, application. These must be checked by the user prior to submission
- The complete test suite can run using:
```
 ./tests/run_tests.bash 
```
- The unit tests only can be run using:
```
 ./tests/unit_tests.bash 
```
- The style tests only can be run using:
```
 python ./tests/style_tests.bash 
```
  - If the cpplint or pylint style tests fail, the output giving the cause can be found in tmp/cpplint.out and tmp/pylint.out respectively
- The application tests only can be run using:
```
 ./tests/application_tests.bash 
```
All new code added to the trunk should be checked in one or more tests
- Unit tests should be written for each method for each class. Examples of unit tests can be found in MAUS under tests/cpp_unit/ and tests/py_unit/
- Unit test coverage can be checked using lcov. We aim for a line coverage of about 80% or better. To generate the lcov output:
  - Set maus_lcov=1 in env.sh
  - Source env.sh
  - Clean and rebuild MAUS
  - Run the unit tests
  - Look at the output in doc/cpp_coverage/index.html
- Application tests should be written to test an overall area of functionality within the code e.g. the tracker reconstruction

Style requirements¶

In principle, all new code added to the trunk should obey the MAUS style guide. In practice, the guide is rather long, and passing the style tests is sufficient (though code may still be rejected on the grounds of style if you do something particularly ugly that still manages to get past the tests).

See the guide at Coding style. Note: although it is quite long, there is lots of good programming advice inside.

Other requirements¶

All new code added to the trunk should not generate any compiler warnings
Code should be well commented; in particular all classes, methods and members should have doxygen comments describing them
If your code modifies or exposes a user interface, this must be documented (either changes an output file or uses an input file)
There should be no memory leaks
Be mindful of what your code does to the overall speed of MAUS
If you really need to generate temporary output files outside of the standard MAUS::Output modules, then these should go in the tmp/ directory within MAUS
At some point the work should be documented in the MAUS user guide

Proposing a merge¶

The preferred method of proposing a merge is to use the Launchpad dedicated merge proposal system, described at https://help.launchpad.net/Code/Review. In summary, go to your branch overview page on Launchpad and click Propose for merging into another branch, then follow the on-screen instructions. The target branch should be set to 'Other' and the merge branch selected:

lp:maus/merge

This begins a conversation with the MAUS release managers on your proposed changes. Once they are satisfied, they will merge your code into the merge branch. When the next release is produce including your code, the review is automatically closed.

MAUS release managers¶

Only release managers have permission to merge to the trunk directly. If you are a release manager, you can have a go at merging your branch with the trunk. First pull down a clean copy of the trunk:

bzr branch lp:maus/merge merge

Build the trunk, and make sure the tests pass. Next, merge in your development branch to the trunk.

bzr merge --preview lp:~my_launchpad_id/maus/my_feature_branch

to see what the result of your merge will be.

If you are sure you want to go ahead, do
```
bzr merge lp:~my_launchpad_id/maus/my_feature_branch 
```
and bzr will put a diff of the conflicts in your working directory. Each file with a conflict will get lines like
```
+<<<<<<< TREE
<text from the trunk>
+=======
<text from the changes>
+>>>>>>> MERGE-SOURCE
```
Go through, fix the diffs, then do
```
bzr resolve <file1> <file2>
```
Review what files were changed. 'M' means modified. Make sure that you haven't made any unintentional changes.
```
bzr status
```
Then do
```
bzr commit -m '<purpose of new code>'
bzr push lp:maus/merge
```
NB: Make sure you only push from the trunk branch you just pulled down, not the original feature branch you developed in (otherwise your commit comments will take precedent over the existing trunk comments, and you will have a vengeful head of MAUS to contend with.)
Monitor the status on the trunk builds on Jenkins at http://test.mice.rl.ac.uk/view/Trunk/ . If any of the builds break, it is your responsibility to fix them.
Once the trunk Jenkins builds all pass, email the head of MAUS with a summary of the changes to you have made.

Your code has now been successfully merged to the trunk

Files (0)

Updated by Franchini, Paolo about 5 years ago · 38 revisions locked

Project

General

Profile

Wiki