|
|
|
> This needs updating to a slightly different git branching model based on [this](http://nvie.com/posts/a-successful-git-branching-model/).
|
|
|
|
|
|
|
|
We are using git via GitHub as the main source control mechanism for MathJax. At the same time, we will also be releasing MathJax 1.1 near the end of the year, and we already have minor point releases to the MathJax 1.0 release to manage. Finally, we would like to begin hosting MathJax through a CDN, which has high requirements both for timely bug fixes and stability.
|
|
|
|
|
|
|
|
Consequently, we need to begin following a more systematic and controlled plan for source control. This document lays out that plan.
|
|
|
|
|
|
|
|
### Requirements
|
|
|
|
|
|
|
|
Looking at all uses outlined above that our source control plan has to accommodate, we obtain these requirements:
|
|
|
|
|
|
|
|
* We need a "master" branch for active development. While we will attempt to keep the master stable, it will change rapidly as development proceeds. It follows no users should use the master branch for production purposes.
|
|
|
|
* We need stable "release" branches that are always guaranteed to point to a stable, tested version. These are branches that users can use for production.
|
|
|
|
* We need to be able to make Hotfixes for bugs to releases and deploy them as "point releases" between major releases.
|
|
|
|
* We need to be able to use source control to share "candidate release" files for testing before releasing them as major or hotfix releases.
|
|
|
|
* We need to periodically package release snapshots for distribution (e.g. zip files) and be able to restore via source control to the code state corresponding to any given snapshot.
|
|
|
|
|
|
|
|
Note that the requirements basically identify two roles for source control.
|
|
|
|
* It serves the needs of the development process by allowing developers to work independently, merge work together, and maintain a history of code state.
|
|
|
|
* It seves as a distribution mechanism for obtaining released software and Hotfixes.
|
|
|
|
|
|
|
|
Many projects use only a single master code line and don't maintain release branches. The reason we want to do this is that we anticipate users who will need hotfixes (e.g. for bugs introduced by browser updates) but that won't want to update to the master development line. For example, if a user has customizations that would need updates due to changes in the master line unrelated to the hotfix, they may not have time and resources to do that work just to get the hotfix.
|
|
|
|
|
|
|
|
For a case study of another organization with similar requirements and their usage of Git to support them, see
|
|
|
|
http://dev.innovationfactory.nl/2010/06/09/development-and-release-strategy-with-git/
|
|
|
|
|
|
|
|
|
|
|
|
### Source Control Lines and Usage
|
|
|
|
|
|
|
|
The Model
|
|
|
|
|
|
|
|
Since branching and merging are lightweight and fundamental operations in Git, we will take advantage of that. The basic model is:
|
|
|
|
|
|
|
|
* In the MathJax repository at GitHub, there is
|
|
|
|
a single master line for development
|
|
|
|
multiple release branches, primarily for code distribution and archival purposes
|
|
|
|
* The MathJax master line represents the most recent stable development version
|
|
|
|
* Developers work in personnel forks of the MathJax repository, using feature branches as necessary to encapsulate work
|
|
|
|
* When a block of work has been reviewed and tested, it is merged into the master line at GitHub. In this way, we attempt to keep the master stable.
|
|
|
|
* The MathJax release lines represent the most recent stable production versions
|
|
|
|
* The only submissions in a release line is the initial version, corresponding to a packaged snapshot, and any subsequent hotfixes.
|
|
|
|
* When a hotfix is needed, a developer would prepare a branch of of the release line (in his or her fork of the repository, and complete the coding. QA would then test that branch. When the branch passes testing, it would be merged to the release branch in the MathJax repository at GitHub.
|
|
|
|
* Independently, a separate branch of MathJax/master would be prepared and the fix merged with it in the developer's repository. That branch would also be tested, and when it passed, the hotfix would be merged to MathJax/master on GitHub as well.
|
|
|
|
* For packaging snapshots, we will tag points on our release branches, and package the distribution ourselves. We may be able to exclusively rely on GitHubs file download manager, but in the short term, we will also continue to host downloads at SourceForge.
|
|
|
|
|
|
|
|
|
|
|
|
### Testing
|
|
|
|
|
|
|
|
Note that a key concept for both the MathJax/master and MathJax/release code lines is that only tested code will be merged in. The model for testing is that a developer implements a work item in a feature branch or branches created however the developer deems appropriate. When work is complete, however, the developer then prepares a testing branch in his or her fork of the MathJax repository.
|
|
|
|
|
|
|
|
The testing branch may be the development branch, but the key property is that any changes in the line into which it is to be merged (typically MathJax/master) that have occured during implementation are merged into the testing branch and all conflicts resolved. Thus the testing branch represents the state that master will be in after the feature is merged into it.
|
|
|
|
|
|
|
|
Once that testing branch is ready, the feature is marked as ready for review, and is tested. According to our [[Development Process]], the review and testing is currently the responsibility of either Davide or Sean. Provided it passes testing, it is then to be merged. For now, Davide will be responsible for all merges into the MathJax master and release lines on GitHub.
|
|
|
|
|
|
|
|
### SVN Mirror
|
|
|
|
|
|
|
|
We will mirror our GitHub repository to the old SVN repository on SourceForge. The MathJax/master line should go to the trunk/. Ideally the release lines should be mirrored to the tags/ lines in SVN, but this may not be worth the effort.
|
|
|
|
|
|
|
|
We will only do one way mirroring, GitHub -> SourceForge. There should be no further check-ins to the SVN repo.
|
|
|
|
|
|
|
|
### Transitioning our current source code repository.
|
|
|
|
|
|
|
|
Currently, in our SVN/trunk and GitHub/master lines are in sync and being mirrored.
|
|
|
|
|
|
|
|
To move to the master-and-release model proposed above, we should
|
|
|
|
Branch MathJax/master to create a MathJax/mathjax-1.0.1 release line
|
|
|
|
Continue with MathJax 1.1 development work in MathJax/master |
|
|
|
\ No newline at end of file |
