4. Development Guide (Branching Commiting Releasing)
The project started and continued in the master branch which is the default branch created by Github, for the first 40 commits, while the program was being launched from scratch by a single individual. Once a certain level of maturity was reached in the program's core architecture (at a milestone of 3000+ lines of code), a branching and versioning model was adopted to facilitate group development and tracking of changes and stable versions.
The branching model specifies the use of 3 branch types, described as follows.
http://nvie.com/posts/a-successful-git-branching-model/
Contains only stable, tested commits which are usable in a runtime environment. All significant commits must possess a version number.
We consider origin/master to be the main branch where the source code of HEAD always reflects a production-ready state. Each time when changes are merged back into master, this is a new production release by definition. This is very strict.
Responsible for code that is in preparation to be integrated into the master branch. Any tentatively completed feature branches are to be merged into this branch for validation.
We consider origin/develop to be the main branch where the source code of HEAD always reflects a state with the latest delivered development changes for the next release. Some would call this the “integration branch”. When the source code in the develop branch reaches a stable point and is ready to be released, all of the changes should be merged back into master somehow and then tagged with a release number.
A new feature branch is created for each new major feature/bug fix/improvement/etc. taken on by a developer. They are temporary and should be closed either when merged or when no longer needed. There is no guarantee that a feature branch will ever be merged.
Feature branches are used to develop new features for the upcoming or a distant future release. TIt exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).
Two-step merging must be performed in when integrating a feature/ branch into develop, and especially develop into master.
- Checkout the active branch, and merge the merge-to branch to the active branch, resolving any conflicts and performing required testing. Make sure to commit the merge results.
- Check out the merge-to branch, and merge the desired branch to it. There should be no conflicts. Make sure to commit the merge results.
Notes:
- This process ensures that the code in the merge-to branch (develop or master) is always functional. Any "mess" from conflict resolution or bug fixes is limited to the feature branch.
- Ensure that any changes have been pulled before the first step, and that the second step of the merge is performed in a timely manner. If not the merge may not be done towards the latest merge-to branch commit, resulting in a split head and the necessity of merging again.
In the commit description provide a brief but comprehensive summary of what you have done. If additional details are deemed critical, add them on extra lines. (messages should try to mention as many change themes, but not HOW they were done. This will make it easier to find when a change was effected by looking at the commits list.)
Fully stable and ready to deploy to runtime, used to indicate the most significant possible developmental milestone, initiate a new phase of development.
When you make incompatible API changes.
Also fully stable and ready to deploy in runtime, used to indicate a major functionality milestone, could lead to a major release with iteration.
When you add functionality in a backwards-compatible manner.
Also fully stable and ready to deploy to runtime, used to make a minor reliability change, does not affect expected functionality or add a new major feature.
When you make backwards-compatible bug fixes.
Interesting read about the use of the words MUST/NOT/SHOULD/NOT/MAY. https://tools.ietf.org/html/rfc2119
http://keepachangelog.com/en/1.0.0/
Every new release should contain a new entry of the following format and any necessary categories.
## [MAJOR.MINOR.PATCH] - YYYY-MM-DD
### Category
- Item
- Added: new features.
- Changed: changes in existing functionality.
- Deprecated: soon-to-be removed features.
- Removed: now removed features.
- Fixed: any bug fixes.