We have 5 types of branches: Master, Staging, Feature, Hotfix, and LTS.
Contributors are welcome to make pull requests to Staging, Feature, Hotfix, and LTS. Contributors are welcome to make pull requests to create new Feature, Hotfix, and LTS branches. No code is required to create a pull request for a new Feature branch if it is a mere proposal.
Maintainers manage the merging between branches and any releases that follow.
The term "stable" is used when all tests pass and the branch is deemed reliable in the context of the project. This does not include the project's dependencies, including platform.
"LTS.md" is a file in the root of a repository with a list of long-term support in a format that can be easily human & machine parsed, if the project has an LTS release. The project's README.md should link to this file, if it exists, for the convenience of visitors. The file should be in markdown table format with LTS, Started, Expires, and Notes columns. The LTS column should match the lts branch's name, minus the 'lts-' prefix and the Started and Expires columns should be in YYYY-MM-DD format. The dates coorespond with 00:00 (midnight) in UTC to avoid time/timezone ambiguity. Example:
| LTS | Started | Expires | Notes |
|---|---|---|---|
| 1.x | 2017-08-01 | 2019-08-01 | The first LTS release (the lts-1.x branch) |
| 2.x | 2018-01-31 | 2020-01-31 | The second LTS release. This is an example for a link |
Name: master
The public, default, go-to branch that we know and love. Git tags are generated whenever new commits are merged to this branch. This branch will be tagged in accordance to Semantic Versioning 2.0.0, even if it means rapid-release of major versions.
Name: staging
The branch where future features and releases are prepared for master. While this branch is under constant development, it aims to be stable at all times (thus encourages quality commits and contributions). This branch must be stable before being merged onto master.
This branch must also contain an up-to-date LTS.md file as well, if any LTS releases are available.
Name: feature-NAME, where NAME is an alias or title of the feature.
A branch for new features, especially those that require long-term development, discussion, and/or wait on a particular dependency/event (such as a platform update). New feature branches should be created by branching from Staging.
Once the new feature is ready to be implemented, the current Staging branch should be re-merged onto the branch to handle any conflicts on the feature branch rather than the Staging branch. Once successfully merged to Staging the branch should not be updated anymore and is kept only for archival purposes.
Name: hotfix-NAME where NAME is an alias or title of the fix.
A branch for any emergencies fixes, usually for security purposes. Once stable, this branch is merged directly onto Master, Staging, and any active LTS (where fix is applicable) then deleted. Once merged onto Master a new tag must be created.
Name: lts-MAJOR_VERSION.x, where MAJOR_VERSION is the major version of the lts
An optional branch for any LTS releases created from Master. LTS releases can be useful if the project requires long-term reliability of APIs for dependents. The information for an LTS.md branch can be found in LTS.md at the root of the repository.
LTS branches may have unique configuration and scripts to simplify builds and releases. An example for an npm package:
"publishConfig": {
"tag": "1.x"
},
"scripts": {
"prepublishOnly": "node tools/special-build-for-lts-1.x.js"
}- In this example:
publishConfig.tagallows you to runnpm publishwithout worrying about accidentally overwriting the default distribution tag ('latest') upon publishing. Runnpm info npm dist-tagsto see a real-world example for how this can be useful.scripts.prepublishOnlyuseful for unique builds for an LTS branch - triggers onnpm publish
Once support has been dropped, the branch should not be updated anymore and is kept only for archival purposes.
- make contributing and maintaining projects as simple as possible, especially for those new to
git. - should be 'welcoming' to innovation so that people can feel comfortable (at any experience level) to make a contribution of any size.
Maintainers may find git branch --set-upstream-to handy. See the following example:
# Set local staging to track origin's staging
git checkout staging
git branch --set-upstream-to origin/staging
# Set local master to track origin's master
git checkout master
git branch --set-upstream-to origin/master
# check which local branch is watching which origin branch
git branch -vv