-
Notifications
You must be signed in to change notification settings - Fork 0
Standards
Hi everybody!
I'm hoping this page can document directly, or have links to pages, with documentation regarding coding standards that we all use.
- mcRoot is the stand-in for the top-level of the git work tree. For example, my git repository may live at ~/repos/MethodsCore, but Mike's might be at ~/gitstuff/Mike/MethodsCore. Throughout documentation (and even in some functions) we use mcRoot to refer to this path.
Similar to how SPM does it, custom functions that we write that we anticipate being shared across packages should start with mc_. For example, mc_GenPath.m is used by a variety of our "central" scripts.
This scripts will live in mcRoot/matlabScripts/ and many of our functions will add this path.
There is one major repository, called universe throughout, though your alias for it may vary.
This repository is policed by group policy and review.
Each developer will also have his or her own repository. It is expected that users may freely fetch from this repository, but for the most part only the owner will ever push or write to it.
All of these branches will live in universe
public This branch tracks currently released versions of the repository. It will update slowest.
develop This branch tracks work in progress. Features based on develop will affect the whole repository, or at least several toolboxes. Examples include changes to deployment hooks, large restructuring, etc.
releaseX.Y There will be several of these branches. Each time we are approaching a new release, we will start one of these branches.
Each "toolbox" will have its own set of branches. Let's use the svmbatch toolbox as an example throughout this document.
svmbatch_alpha Rapid iteration. This branch collects features when their developer believes that are reasonably ready to go. Pull requests to svmbatch_alpha should generally only require sign off of the feature's developer.
svmbatch_beta Semi-quick iteration. This branch periodically advances by merging in svmbatch_alpha. Pull requests to svmbatch_beta should only include svmbatch_alpha (or its parents, since it is a frequently moving target). Adoption of pull requests should get at least a +1 from two developers (the pull requester and one other developer). +1's don't necessarily indicate that the new code has been tested, but the diff has been reviewed and looks reasonable.
svmbatch_stable Slower iteration.
-
This branch periodically advances by merging in svmbatch_beta. Pull requests to svmbatch_stable should only include svmbatch_alpha (or its parents, since it is a moving target). Adoption of pull requests should get at least a +1 from two developers (the pull requester and one other developer), but beyond just reading the diff they should actually test it.
-
This branch also periodically advances by merging in develop. This way, any repository wide changes or bugfixes will make their way back to the toolbox branch
For this example, we'll be adding support for libsvm to svmbatch.
- Update your local repository from universe
git fetch universe - Base your new branch off of svmbatch_stable, and name it using toolbox/featurename syntax
git checkout universe/svmbatch_stable -b svmbatch/libSVM_support - Do work in your svmbatch/libSVM_support branch
git commit -am "added support for libSVM" - Perform some sort of testing or sanity check to make sure your code doesn't break anything in a really obvious way.
- Push your feature branch to your repository
git push github/dankessler svmbatch/libSVM_support - Submit pull request to merge your feature branch into svmbatch_alpha using github. Be careful to be sure that your request sets the Base Branch to UMPsychMethodsCore@svmbatch_alpha and NOT develop
- Write up some justification or explanation of what your feature does, and go ahead and adopt the pull request.
For this example, we'll be updating the deployment hooks for the whole repository
- Update your local repository from universe
git fetch universe - Base your new branch off of develop, and name it using core/featurename syntax `git checkout universe/develop -b core/deployment_hooks
- Do work in your core/deployment_hooks branch
git commit -am "updated deployment hooks process" - Perform some semi-rigorous testing to make sure you're not breaking anything.
- Push your feature branch to your repository
git push github/dankessler core/deployment_hooks - Submit pull request to merge your feature branch into develop using github. Your base branch will be UMPsychMethodsCore@develop, and your head branch will be dankessler@core/deployment_hooks
- Write up some justification or explanation of what your feature does, and ideally also mention which issue it addresses.
- Assign the pull request to somebody else. Allow discussion to follow. At least one other person should sign off on it, and they should have at least tested it.
- The assignee accepts the pull request, and develop is updated.
We'll stick with the @dankessler working on svmbatch example we've used throughout.
The work being done in the feature branches, and collected in the alpha branches, should percolate up towards development. Its first steps are via the beta channels. From time to time, ideally an assigned toolbox maintainer will do the following
- Update local repository from universe
git fetch universe - Base a new pre_beta branch off of the alpha channel. Any necessary fixes discovered in the course of testing will go on this branch.
git checkout universe/svmbatch_alpha -b svmbatch_pre_beta - It'd probably be wise to review what's been added to alpha since it was last moved to beta. Check this range of commits using gitk
gitk universe/svmbatch_beta..svmbatch_pre_beta - Based on what was identified in 3 above, do some testing of svmbatch functionality. It'd be really awesome if we had some test data that we could use for benchmarking and to quickly ensure that no existing functionality is broken by addition of new features. Testing new features is harder, since it's trickier to know what the expected output will be.
- Make any fixes necessary to successfully complete testing
git commit -am "fixed bug with svmbatch introduced in commit 6xyy2..." - There may be some features that are simply not ready for inclusion in the beta channel, even though they exist in the alpha channel. In this case, you'll need to revert the merge that brought them in. There's a pretty detailed treatment of that subject here. Undoing merges is tricky, especially if you want to later undo the undo of the merge, so just go read that if you need to undo a merge.
- Push your changes to your repository
git push github/dankessler svmbatch_pre_beta - Submit pull request to merge your feature branch into develop using github. Your base branch will be UMPsychMethodsCore@svmbatch_beta, and your head branch will be dankessler@svmbatch_pre_beta
- Write up some justification or mini changelog based on what you saw back in step 3. Also make sure to discuss any fixes you had to make in 5, and deal with any features that you un-included in 6.
- Assign the pull request to yourself.
- Wait for a +1 from another developer who at least reads your diff, then accept the pull request.
- If you made any new commits in 5 or 6, these new changes will no longer be in the alpha channel. The alpha channel should at least be caught up with the beta channel, so you'll need to do a quick pull request to update the alpha channel. You'll do this in github. Your base branch will be UMPsychMethodsCore@svmbatch_alpha, and your head branch will be (recently updated in step 11) UMPsychMethodsCore@svmbatch_beta. Write a quick message indicating that you are updating svmbatch_alpha to incorporate fixes applied in a beta release, and then go ahead and accept it.
Semi-frequently, the work being collected in the beta channels should be tested and percolate to the stable channels for inclusion in a future release. This process will be very similar to that for Updating Beta Channels, but we'll be specific. However, an important addition to this process is that whenever the stable channel is updated, it should also incorporate develop to take advantage of any repository wide features or improvements.
- Update local repository from universe
git fetch universe - Base a new pre_stable branch off of the beta channel. Any necessary fixes discovered in the course of testing will go on this branch.
git checkout universe/svmbatch_beta -b svmbatch_pre_stable - Update your branch with the latest from develop
git merge universe/develop - It'd probably be wise to review what's been added to beta since it was last moved to stable. Check this range of commits using gitk
gitk universe/svmbatch_stable..svmbatch_pre_stable - Based on what was identified in 3 above, do some testing of svmbatch functionality. It'd be really awesome if we had some test data that we could use for benchmarking and to quickly ensure that no existing functionality is broken by addition of new features. Testing new features is harder, since it's trickier to know what the expected output will be.
- Make any fixes necessary to successfully complete testing
git commit -am "fixed bug with svmbatch introduced in commit 6xyy2..." - There may be some features that are simply not ready for inclusion in the stable channel, even though they exist in the beta and alpha channels. In this case, you'll need to revert the merge that brought them in. There's a pretty detailed treatment of that subject here. Undoing merges is tricky, especially if you want to later undo the undo of the merge, so just go read that if you need to undo a merge.
- Push your changes to your repository
git push github/dankessler svmbatch_pre_stable - Submit pull request to merge your feature branch into develop using github. Your base branch will be UMPsychMethodsCore@svmbatch_stable, and your head branch will be dankessler@svmbatch_pre_stable
- Write up some justification or mini changelog based on what you saw back in step 3. Also make sure to discuss any fixes you had to make in 5, and deal with any features that you un-included in 6.
- Assign the pull request to yourself.
- Wait for a +1 from another developer who has actually tested your code, then accept the pull request.
- If you made any new commits in 5 or 6, these new changes will not be in the alpha or beta channels. The alpha and beta channels should at least be caught up with the stable channel, so you'll need to do two quick pull requests to update the alpha and beta channels. You'll do this in github. Your base branches will be UMPsychMethodsCore@svmbatch_alpha OR UMPsychMethodsCore@svmbatch_beta, and your head branch for both will be (recently updated in step 11) UMPsychMethodsCore@svmbatch_stable. Write a quick message indicating that you are updating svmbatch_alpha or svmbatch_beta to incorporate fixes applied in a stable release, and then go ahead and accept it.
When a release is approaching, we will need to gather together feature branches along with the current version of develop.
Let's imagine that we are preparing to release version 2.3, and it will include several new features from svmbatch and som toolboxes.
- Update local repository from universe
git fetch universe - Base a new release branch off the develop branch
git checkout universe/develop -b release/2.3 - Gather changes from the toolboxes that are to be included in this next release. I'm not sure whether it's better to merge them in serially using recursive merges or to try an octopus merge. Let's assume the octopus merge works, but we won't really know til we get there
git merge universe/svmbatch_stable universe/som_stable - Review the diff resulting from the merge to identify what functions/features were touched. You may wish to check using git diff
git diff HEAD^ HEAD - Perform rigorous testing.
- Make any changes necessary to pass testing
git commit -am "fixed bugs" - Push your changes to your repository
git push github/dankessler release/2.3 - Submit pull request to merge your release branch into public. Your base branch will be UMPsychMethodsCore@public while your head branch will be dankessler@release/2.3
- You should probably get a +1 from the rest of the development team, who will be broken down into testing teams, and official approval will probably come from a unanimous vote at a MethodsCore meeting or something like that.
- Make any necessary commits to address testing issues, and repeat testing to ensure that they actually address problems.
- Update your pull request with these changes by re-pushing your updated branch
git push github/dankessler release/2.3 - Accept the pull request.
- Update your repository again
git fetch universe - Tag the new release in the public branch
git tag -a Release_2.3 universe/public. In the editor, write the release number and some description of the release. - Push your tag to the remote `git push universe tag Release_2.3
- Any of the fixes introduced in 10 will not be on the develop channel, and thus won't get rolled into stable branches when they are updated. Correct this by pulling the changes in public back into develop. Open a pull request with base branch UMPsychMethodsCore@develop and head branch UMPsychMethodsCore@public. Make a quick note to indicate you're updating the develop branch to include changes from a recent public release, then go ahead and accept the pull request.