From ca50e4136009e0681ed7c53d059d064e04408f74 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sat, 1 Jul 2017 21:13:22 +0100 Subject: [PATCH] Add remainder of requirements, author and license info --- common-flow.md | 86 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 62 insertions(+), 24 deletions(-) diff --git a/common-flow.md b/common-flow.md index fc131f2..8a97346 100644 --- a/common-flow.md +++ b/common-flow.md @@ -26,14 +26,16 @@ Terminology: - Release - Consists of a version bump commit directly on the master branch, and a git tag named according to the new version number placed on said commit. -Basic Requirements: +Basics: -- The "master" branch should always be deployable/usable, while also - considered to be bleeding edge. +- The "master" branch should always be deployable/usable, while also considered + to be bleeding edge. - New work must be done on a descriptively named change branch created off of the master branch. - Commit to the change branch locally, and regularly push your work to the same named branch on the remote server. +- The change branch MUST be kept up to date with the master branch by rebasing + it on top of the remote master branch. - When you need feedback, help, or think the branch is ready for merging, open a pull request. - After someone else has reviewed and signed off on the change, you can merge it @@ -60,29 +62,65 @@ interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). branch, and they MUST have descriptive names. You SHOULD commit often locally, and you SHOULD regularly push your work to the same named branch on the remote server. -3. To merge a change branch back in to the master branch, you MUST open a Pull - Request (or equivalent) so others can review and approve your changes. A - change branch MUST only be merged in to master when you and others are - certain that it is ready for release and/or deployment to production. -4. To get feedback, help, or generally just discuss a change branch with others, - you SHOULD create a pull request (or equivalent). -5. The project MUST have it's version hard-coded somewhere in project. It is - RECOMMENDED that this is done in a "VERSION" file in the root of the project, - which only contains the exact version string. -6. The version string SHOULD follow the Semantic Versioning (http://semver.org/) +3. Change branches MUST be regularly updated with any changes on the master + branch. This MUST be done by rebasing the change branch on top of the remote + master branch ("git rebase origin/master"). To be clear you MUST NOT merge + the master branch into a change branch. +4. To merge a change branch back in to the master branch, you MUST open a "pull + request" (or equivalent) so others can review and approve your changes. A + change branch MUST only be merged in to the master branch when you and others + are certain that it is ready for release and/or deployment to production. +5. To get feedback, help, or generally just discuss a change branch with others, + you SHOULD also create a pull request and discuss the changes with others + there. +6. The project MUST have its version hard-coded somewhere in the code-base. It + is RECOMMENDED that this is done in a file called "VERSION" located in the + root of the project, and that it only contains the exact version string. +7. The version string SHOULD follow the Semantic Versioning (http://semver.org/) format. Use of Semantic Versioning is OPTIONAL, but the version string MUST NOT have a "v" prefix. For example "v2.11.4" is bad, and "2.11.4" is good. -7. To create a new release, you MUST create a "version bump" commit directly on +8. To create a new release, you MUST create a "version bump" commit directly on the master branch which changes the hard-coded version value of the - project. The version bump commit MUST then have a lightweight git tag created - on it named as the exact version string. -8. A version bump commit MUST have a commit message title of "Bump version to - VERSION". For example, if the new version string is "2.11.4", the first - line of the commit message MUST read "Bump version to 2.11.4". -9. The release tag on the version bump commit MUST be named exactly the same as - the version string. And its name MUST NOT have a "v" prefix. -10. OPTIONALLY you can create the release tag as a annotated tag where the - annotation message is the changelog since the last release. -11. If a change branch which has been merged in to master is found to have a bug + project. The version bump commit MUST have a lightweight git tag created on + it and named as the exact version string. +9. A version bump commit MUST have a commit message title of "Bump version to + VERSION". For example, if the new version string is "2.11.4", the first line + of the commit message MUST read: "Bump version to 2.11.4" +10. The release tag on the version bump commit MUST be named exactly the same as + the version string. And its name MUST NOT have a "v" prefix. +11. OPTIONALLY you can create the release tag as a annotated tag where the + annotation message is the changelog since the last release. +12. If a change branch which has been merged in to master is found to have a bug in it, the bug fix work MUST be done as a new separate change branch and MUST follow the same workflow as any other change branch. +13. If a change branch is wrongfully merged in to master, or for any other + reason the merge must be undone, you MUST undo the merge by reverting the + merge commit self. Effectively creating a new commit that reverses all the + relevant changes. The master branch MUST NOT under any circumstance be + rewound to a earlier commit. +14. Maintenance branches are used for managing new releases for older + versions. Typically this is used to provide security updates for older + versions when the master branch has moved on. A maintenance branch SHOULD + follow a "stable-X.Y" naming pattern, where "X" is the MAJOR version and "Y" + is the minor version. +15. Updating a maintenance branch is done by cherry picking the relevant commits + if possible. If not possible it MUST be done via a change branch created off + of the maintenance branch, and reviewed through a pull request like any + other change request. +16. Creating a release from a maintenance branch is done the same way as a + normal release, except everything is done on the maintenance branch instead + of the master branch. + +About +----- + +The Git Common-Flow specification is authored +by [Jim Myhrberg](http://jimeh.me). + +If you'd like to leave feedback, +please [open an issue on GitHub](https://github.com/jimeh/common-flow/issues). + +License +------- + +[Creative Commons - CC BY 3.0](http://creativecommons.org/licenses/by/3.0/)