-
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 betachannel. 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.