├── LICENSE
├── VERSION
├── common-flow.md
└── common-flow.svg
/LICENSE:
--------------------------------------------------------------------------------
1 | Attribution 4.0 International
2 |
3 | =======================================================================
4 |
5 | Creative Commons Corporation ("Creative Commons") is not a law firm and
6 | does not provide legal services or legal advice. Distribution of
7 | Creative Commons public licenses does not create a lawyer-client or
8 | other relationship. Creative Commons makes its licenses and related
9 | information available on an "as-is" basis. Creative Commons gives no
10 | warranties regarding its licenses, any material licensed under their
11 | terms and conditions, or any related information. Creative Commons
12 | disclaims all liability for damages resulting from their use to the
13 | fullest extent possible.
14 |
15 | Using Creative Commons Public Licenses
16 |
17 | Creative Commons public licenses provide a standard set of terms and
18 | conditions that creators and other rights holders may use to share
19 | original works of authorship and other material subject to copyright
20 | and certain other rights specified in the public license below. The
21 | following considerations are for informational purposes only, are not
22 | exhaustive, and do not form part of our licenses.
23 |
24 | Considerations for licensors: Our public licenses are
25 | intended for use by those authorized to give the public
26 | permission to use material in ways otherwise restricted by
27 | copyright and certain other rights. Our licenses are
28 | irrevocable. Licensors should read and understand the terms
29 | and conditions of the license they choose before applying it.
30 | Licensors should also secure all rights necessary before
31 | applying our licenses so that the public can reuse the
32 | material as expected. Licensors should clearly mark any
33 | material not subject to the license. This includes other CC-
34 | licensed material, or material used under an exception or
35 | limitation to copyright. More considerations for licensors:
36 | wiki.creativecommons.org/Considerations_for_licensors
37 |
38 | Considerations for the public: By using one of our public
39 | licenses, a licensor grants the public permission to use the
40 | licensed material under specified terms and conditions. If
41 | the licensor's permission is not necessary for any reason--for
42 | example, because of any applicable exception or limitation to
43 | copyright--then that use is not regulated by the license. Our
44 | licenses grant only permissions under copyright and certain
45 | other rights that a licensor has authority to grant. Use of
46 | the licensed material may still be restricted for other
47 | reasons, including because others have copyright or other
48 | rights in the material. A licensor may make special requests,
49 | such as asking that all changes be marked or described.
50 | Although not required by our licenses, you are encouraged to
51 | respect those requests where reasonable. More_considerations
52 | for the public:
53 | wiki.creativecommons.org/Considerations_for_licensees
54 |
55 | =======================================================================
56 |
57 | Creative Commons Attribution 4.0 International Public License
58 |
59 | By exercising the Licensed Rights (defined below), You accept and agree
60 | to be bound by the terms and conditions of this Creative Commons
61 | Attribution 4.0 International Public License ("Public License"). To the
62 | extent this Public License may be interpreted as a contract, You are
63 | granted the Licensed Rights in consideration of Your acceptance of
64 | these terms and conditions, and the Licensor grants You such rights in
65 | consideration of benefits the Licensor receives from making the
66 | Licensed Material available under these terms and conditions.
67 |
68 |
69 | Section 1 -- Definitions.
70 |
71 | a. Adapted Material means material subject to Copyright and Similar
72 | Rights that is derived from or based upon the Licensed Material
73 | and in which the Licensed Material is translated, altered,
74 | arranged, transformed, or otherwise modified in a manner requiring
75 | permission under the Copyright and Similar Rights held by the
76 | Licensor. For purposes of this Public License, where the Licensed
77 | Material is a musical work, performance, or sound recording,
78 | Adapted Material is always produced where the Licensed Material is
79 | synched in timed relation with a moving image.
80 |
81 | b. Adapter's License means the license You apply to Your Copyright
82 | and Similar Rights in Your contributions to Adapted Material in
83 | accordance with the terms and conditions of this Public License.
84 |
85 | c. Copyright and Similar Rights means copyright and/or similar rights
86 | closely related to copyright including, without limitation,
87 | performance, broadcast, sound recording, and Sui Generis Database
88 | Rights, without regard to how the rights are labeled or
89 | categorized. For purposes of this Public License, the rights
90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar
91 | Rights.
92 |
93 | d. Effective Technological Measures means those measures that, in the
94 | absence of proper authority, may not be circumvented under laws
95 | fulfilling obligations under Article 11 of the WIPO Copyright
96 | Treaty adopted on December 20, 1996, and/or similar international
97 | agreements.
98 |
99 | e. Exceptions and Limitations means fair use, fair dealing, and/or
100 | any other exception or limitation to Copyright and Similar Rights
101 | that applies to Your use of the Licensed Material.
102 |
103 | f. Licensed Material means the artistic or literary work, database,
104 | or other material to which the Licensor applied this Public
105 | License.
106 |
107 | g. Licensed Rights means the rights granted to You subject to the
108 | terms and conditions of this Public License, which are limited to
109 | all Copyright and Similar Rights that apply to Your use of the
110 | Licensed Material and that the Licensor has authority to license.
111 |
112 | h. Licensor means the individual(s) or entity(ies) granting rights
113 | under this Public License.
114 |
115 | i. Share means to provide material to the public by any means or
116 | process that requires permission under the Licensed Rights, such
117 | as reproduction, public display, public performance, distribution,
118 | dissemination, communication, or importation, and to make material
119 | available to the public including in ways that members of the
120 | public may access the material from a place and at a time
121 | individually chosen by them.
122 |
123 | j. Sui Generis Database Rights means rights other than copyright
124 | resulting from Directive 96/9/EC of the European Parliament and of
125 | the Council of 11 March 1996 on the legal protection of databases,
126 | as amended and/or succeeded, as well as other essentially
127 | equivalent rights anywhere in the world.
128 |
129 | k. You means the individual or entity exercising the Licensed Rights
130 | under this Public License. Your has a corresponding meaning.
131 |
132 |
133 | Section 2 -- Scope.
134 |
135 | a. License grant.
136 |
137 | 1. Subject to the terms and conditions of this Public License,
138 | the Licensor hereby grants You a worldwide, royalty-free,
139 | non-sublicensable, non-exclusive, irrevocable license to
140 | exercise the Licensed Rights in the Licensed Material to:
141 |
142 | a. reproduce and Share the Licensed Material, in whole or
143 | in part; and
144 |
145 | b. produce, reproduce, and Share Adapted Material.
146 |
147 | 2. Exceptions and Limitations. For the avoidance of doubt, where
148 | Exceptions and Limitations apply to Your use, this Public
149 | License does not apply, and You do not need to comply with
150 | its terms and conditions.
151 |
152 | 3. Term. The term of this Public License is specified in Section
153 | 6(a).
154 |
155 | 4. Media and formats; technical modifications allowed. The
156 | Licensor authorizes You to exercise the Licensed Rights in
157 | all media and formats whether now known or hereafter created,
158 | and to make technical modifications necessary to do so. The
159 | Licensor waives and/or agrees not to assert any right or
160 | authority to forbid You from making technical modifications
161 | necessary to exercise the Licensed Rights, including
162 | technical modifications necessary to circumvent Effective
163 | Technological Measures. For purposes of this Public License,
164 | simply making modifications authorized by this Section 2(a)
165 | (4) never produces Adapted Material.
166 |
167 | 5. Downstream recipients.
168 |
169 | a. Offer from the Licensor -- Licensed Material. Every
170 | recipient of the Licensed Material automatically
171 | receives an offer from the Licensor to exercise the
172 | Licensed Rights under the terms and conditions of this
173 | Public License.
174 |
175 | b. No downstream restrictions. You may not offer or impose
176 | any additional or different terms or conditions on, or
177 | apply any Effective Technological Measures to, the
178 | Licensed Material if doing so restricts exercise of the
179 | Licensed Rights by any recipient of the Licensed
180 | Material.
181 |
182 | 6. No endorsement. Nothing in this Public License constitutes or
183 | may be construed as permission to assert or imply that You
184 | are, or that Your use of the Licensed Material is, connected
185 | with, or sponsored, endorsed, or granted official status by,
186 | the Licensor or others designated to receive attribution as
187 | provided in Section 3(a)(1)(A)(i).
188 |
189 | b. Other rights.
190 |
191 | 1. Moral rights, such as the right of integrity, are not
192 | licensed under this Public License, nor are publicity,
193 | privacy, and/or other similar personality rights; however, to
194 | the extent possible, the Licensor waives and/or agrees not to
195 | assert any such rights held by the Licensor to the limited
196 | extent necessary to allow You to exercise the Licensed
197 | Rights, but not otherwise.
198 |
199 | 2. Patent and trademark rights are not licensed under this
200 | Public License.
201 |
202 | 3. To the extent possible, the Licensor waives any right to
203 | collect royalties from You for the exercise of the Licensed
204 | Rights, whether directly or through a collecting society
205 | under any voluntary or waivable statutory or compulsory
206 | licensing scheme. In all other cases the Licensor expressly
207 | reserves any right to collect such royalties.
208 |
209 |
210 | Section 3 -- License Conditions.
211 |
212 | Your exercise of the Licensed Rights is expressly made subject to the
213 | following conditions.
214 |
215 | a. Attribution.
216 |
217 | 1. If You Share the Licensed Material (including in modified
218 | form), You must:
219 |
220 | a. retain the following if it is supplied by the Licensor
221 | with the Licensed Material:
222 |
223 | i. identification of the creator(s) of the Licensed
224 | Material and any others designated to receive
225 | attribution, in any reasonable manner requested by
226 | the Licensor (including by pseudonym if
227 | designated);
228 |
229 | ii. a copyright notice;
230 |
231 | iii. a notice that refers to this Public License;
232 |
233 | iv. a notice that refers to the disclaimer of
234 | warranties;
235 |
236 | v. a URI or hyperlink to the Licensed Material to the
237 | extent reasonably practicable;
238 |
239 | b. indicate if You modified the Licensed Material and
240 | retain an indication of any previous modifications; and
241 |
242 | c. indicate the Licensed Material is licensed under this
243 | Public License, and include the text of, or the URI or
244 | hyperlink to, this Public License.
245 |
246 | 2. You may satisfy the conditions in Section 3(a)(1) in any
247 | reasonable manner based on the medium, means, and context in
248 | which You Share the Licensed Material. For example, it may be
249 | reasonable to satisfy the conditions by providing a URI or
250 | hyperlink to a resource that includes the required
251 | information.
252 |
253 | 3. If requested by the Licensor, You must remove any of the
254 | information required by Section 3(a)(1)(A) to the extent
255 | reasonably practicable.
256 |
257 | 4. If You Share Adapted Material You produce, the Adapter's
258 | License You apply must not prevent recipients of the Adapted
259 | Material from complying with this Public License.
260 |
261 |
262 | Section 4 -- Sui Generis Database Rights.
263 |
264 | Where the Licensed Rights include Sui Generis Database Rights that
265 | apply to Your use of the Licensed Material:
266 |
267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right
268 | to extract, reuse, reproduce, and Share all or a substantial
269 | portion of the contents of the database;
270 |
271 | b. if You include all or a substantial portion of the database
272 | contents in a database in which You have Sui Generis Database
273 | Rights, then the database in which You have Sui Generis Database
274 | Rights (but not its individual contents) is Adapted Material; and
275 |
276 | c. You must comply with the conditions in Section 3(a) if You Share
277 | all or a substantial portion of the contents of the database.
278 |
279 | For the avoidance of doubt, this Section 4 supplements and does not
280 | replace Your obligations under this Public License where the Licensed
281 | Rights include other Copyright and Similar Rights.
282 |
283 |
284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability.
285 |
286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
296 |
297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
306 |
307 | c. The disclaimer of warranties and limitation of liability provided
308 | above shall be interpreted in a manner that, to the extent
309 | possible, most closely approximates an absolute disclaimer and
310 | waiver of all liability.
311 |
312 |
313 | Section 6 -- Term and Termination.
314 |
315 | a. This Public License applies for the term of the Copyright and
316 | Similar Rights licensed here. However, if You fail to comply with
317 | this Public License, then Your rights under this Public License
318 | terminate automatically.
319 |
320 | b. Where Your right to use the Licensed Material has terminated under
321 | Section 6(a), it reinstates:
322 |
323 | 1. automatically as of the date the violation is cured, provided
324 | it is cured within 30 days of Your discovery of the
325 | violation; or
326 |
327 | 2. upon express reinstatement by the Licensor.
328 |
329 | For the avoidance of doubt, this Section 6(b) does not affect any
330 | right the Licensor may have to seek remedies for Your violations
331 | of this Public License.
332 |
333 | c. For the avoidance of doubt, the Licensor may also offer the
334 | Licensed Material under separate terms or conditions or stop
335 | distributing the Licensed Material at any time; however, doing so
336 | will not terminate this Public License.
337 |
338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
339 | License.
340 |
341 |
342 | Section 7 -- Other Terms and Conditions.
343 |
344 | a. The Licensor shall not be bound by any additional or different
345 | terms or conditions communicated by You unless expressly agreed.
346 |
347 | b. Any arrangements, understandings, or agreements regarding the
348 | Licensed Material not stated herein are separate from and
349 | independent of the terms and conditions of this Public License.
350 |
351 |
352 | Section 8 -- Interpretation.
353 |
354 | a. For the avoidance of doubt, this Public License does not, and
355 | shall not be interpreted to, reduce, limit, restrict, or impose
356 | conditions on any use of the Licensed Material that could lawfully
357 | be made without permission under this Public License.
358 |
359 | b. To the extent possible, if any provision of this Public License is
360 | deemed unenforceable, it shall be automatically reformed to the
361 | minimum extent necessary to make it enforceable. If the provision
362 | cannot be reformed, it shall be severed from this Public License
363 | without affecting the enforceability of the remaining terms and
364 | conditions.
365 |
366 | c. No term or condition of this Public License will be waived and no
367 | failure to comply consented to unless expressly agreed to by the
368 | Licensor.
369 |
370 | d. Nothing in this Public License constitutes or may be interpreted
371 | as a limitation upon, or waiver of, any privileges and immunities
372 | that apply to the Licensor or You, including from the legal
373 | processes of any jurisdiction or authority.
374 |
375 |
376 | =======================================================================
377 |
378 | Creative Commons is not a party to its public
379 | licenses. Notwithstanding, Creative Commons may elect to apply one of
380 | its public licenses to material it publishes and in those instances
381 | will be considered the “Licensor.” The text of the Creative Commons
382 | public licenses is dedicated to the public domain under the CC0 Public
383 | Domain Dedication. Except for the limited purpose of indicating that
384 | material is shared under a Creative Commons public license or as
385 | otherwise permitted by the Creative Commons policies published at
386 | creativecommons.org/policies, Creative Commons does not authorize the
387 | use of the trademark "Creative Commons" or any other trademark or logo
388 | of Creative Commons without its prior written consent including,
389 | without limitation, in connection with any unauthorized modifications
390 | to any of its public licenses or any other arrangements,
391 | understandings, or agreements concerning use of licensed material. For
392 | the avoidance of doubt, this paragraph does not form part of the
393 | public licenses.
394 |
395 | Creative Commons may be contacted at creativecommons.org.
396 |
--------------------------------------------------------------------------------
/VERSION:
--------------------------------------------------------------------------------
1 | 1.0.0-rc.5
2 |
--------------------------------------------------------------------------------
/common-flow.md:
--------------------------------------------------------------------------------
1 | Git Common-Flow {{version}}
2 | ===========================
3 |
4 | Introduction
5 | ------------
6 |
7 | Common-Flow is an attempt to gather a sensible selection of the most common
8 | usage patterns of git into a single and concise specification. It is based on
9 | the [original variant](http://scottchacon.com/2011/08/31/github-flow.html)
10 | of [GitHub Flow](https://guides.github.com/introduction/flow/), while taking
11 | into account how a lot of open source projects most commonly use git.
12 |
13 | In short, Common-Flow is essentially GitHub Flow with the addition of versioned
14 | releases, optional release branches, and without the requirement to deploy to
15 | production all the time.
16 |
17 | Summary
18 | -------
19 |
20 | - The "master" branch is the mainline branch with latest changes, and must not
21 | be broken.
22 | - Changes (features, bugfixes, etc.) are done on "change branches" created from
23 | the master branch.
24 | - Rebase change branches [early and often](https://i.imgur.com/1RS8x2d.png).
25 | - When a change branch is stable and ready, it is merged back in to master.
26 | - A release is just a git tag who's name is the exact release version string
27 | (e.g. "2.11.4").
28 | - Release branches can be used to avoid change freezes on master. They are not
29 | required, instead they are available if you need them.
30 |
31 | Terminology
32 | -----------
33 |
34 | - **Master Branch** - Must be named "master", must always have passing tests,
35 | and is not guaranteed to always work in production environments.
36 | - **Change Branches** - Any branch that introduces changes like a new feature, a
37 | bug fix, etc.
38 | - **Source Branch** - The branch that a change branch was created from. New
39 | changes in the source branch should be incorporated into the change branch via
40 | rebasing.
41 | - **Merge Target** - A branch that is the intended merge target for a change
42 | branch. Typically the merge target branch will be the same as the source
43 | branch.
44 | - **Pull Request** - A means of requesting that a change branch is merged in to
45 | its merge target, allowing others to review, discuss and approve the changes.
46 | - **Release** - May be considered safe to use in production environments. Is
47 | effectively just a git tag named after the version of the release.
48 | - **Release Branches** - Used both for short-term preparations of a release, and
49 | also for long-term maintenance of older version.
50 |
51 | Git Common-Flow Specification (Common-Flow)
52 | -------------------------------------------
53 |
54 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
55 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
56 | interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
57 |
58 | 1. TL;DR
59 | 1. Do not break the master branch.
60 | 2. A release is a git tag.
61 | 2. The Master Branch
62 | 1. A branch named "master" MUST exist and it MUST be referred to as the
63 | "master branch".
64 | 2. The master branch MUST always be in a non-broken state with its test
65 | suite passing.
66 | 4. The master branch IS NOT guaranteed to always work in production
67 | environments. Despite test suites passing it may at times contain
68 | unfinished work. Only releases may be considered safe for production use.
69 | 5. The master branch SHOULD always be in a "as near as possibly ready for
70 | release/production" state to reduce any friction with creating a new
71 | release.
72 | 3. Change Branches
73 | 1. Each change (feature, bugfix, etc.) MUST be performed on separate
74 | branches that SHOULD be referred to as "change branches".
75 | 2. All change branches MUST have descriptive names.
76 | 3. It is RECOMMENDED that you commit often locally, and that you try and
77 | keep the commits reasonably structured to avoid a messy and confusing git
78 | history.
79 | 4. You SHOULD regularly push your work to the same named branch on the
80 | remote server.
81 | 5. You SHOULD create separate change branches for each distinctly different
82 | change. You SHOULD NOT include multiple unrelated changes into a single
83 | change branch.
84 | 6. When a change branch is created, the branch that it is created from
85 | SHOULD be referred to as the "source branch". Each change branch also
86 | needs a designated "merge target" branch, typically this will be the same
87 | as the source branch.
88 | 7. Change branches MUST be regularly updated with any changes from their
89 | source branch. This MUST be done by rebasing the change branch on top of
90 | the source branch.
91 | 8. After updating a change branch from its source branch you MUST push the
92 | change branch to the remote server. Due to the nature of rebasing, you
93 | will be required to do a force push, and you MUST use the
94 | "--force-with-lease" git push option when doing so instead of the regular
95 | "--force".
96 | 9. If there is a truly valid technical reason to not use rebase when
97 | updating change branches, then you can update change branches via merge
98 | instead of rebase. The decision to use merge MUST only be taken after all
99 | possible options to use rebase have been tried and failed. People not
100 | understanding how to use rebase is NOT a valid reason to use merge. If
101 | you do decide to use merge instead of rebase, you MUST NOT use a mixture
102 | of both methods, pick one and stick to it.
103 | 4. Pull Requests
104 | 1. To merge a change branch into its merge target, you MUST open a "pull
105 | request" (or equivalent).
106 | 2. The purpose of a pull request is to allow others to review your changes
107 | and give feedback. You can then fix any issues, complaints, and more that
108 | might arise, and then let people review again.
109 | 3. Before creating a pull request, it is RECOMMENDED that you consider the
110 | state of your change branch's commit history. If it is messy and
111 | confusing, it might be a good idea to rebase your branch with "git rebase
112 | -i" to present a cleaner and easier to follow commit history for your
113 | reviewers.
114 | 4. A pull request MUST only be merged when the change branch is up-to-date
115 | with its source branch, the test suite is passing, and you and others are
116 | happy with the change. This is especially important if the merge target
117 | is the master branch.
118 | 5. To get feedback, help, or generally just discuss a change branch with
119 | others, it is RECOMMENDED you create a pull request and discuss the
120 | changes with others there. This leaves a clear and visible history of
121 | how, when, and why the code looks and behaves the way it does.
122 | 5. Versioning
123 | 1. A "version string" is a typically mostly numeric string that identifies a
124 | specific version of a project. The version string itself MUST NOT have a
125 | "v" prefix, but the version string can be displayed with a "v" prefix to
126 | indicate it is a version that is being referred to.
127 | 2. The source of truth for a project's version MUST be a git tag with a name
128 | based on the version string. This kind of tag MUST be referred to as a
129 | "release tag".
130 | 3. It is OPTIONAL, but RECOMMENDED to also keep the version string
131 | hard-coded somewhere in the project code-base.
132 | 4. If you hard-code the version string into the code-base, it is RECOMMENDED
133 | that you do so in a file called "VERSION" located in the root of the
134 | project. But be mindful of the conventions of your programming language
135 | and community when choosing if, where and how to hard-code the version
136 | string.
137 | 5. If you are using a "VERSION" file in the root of the project, this file
138 | MUST only contain the exact version string, meaning it MUST NOT have a
139 | "v" prefix. For example "v2.11.4" is bad, and "2.11.4" is good.
140 | 6. It is OPTIONAL, but RECOMMENDED that that the version string follows
141 | Semantic Versioning ().
142 | 6. Releases
143 | 1. To create a new release, you MUST create a git tag named as the exact
144 | version string of the release. This kind of tag MUST be referred to as a
145 | "release tag".
146 | 2. The release tag name can OPTIONALLY be prefixed with "v". For example the
147 | tag name can be either "2.11.4" or "v2.11.4". It is however RECOMMENDED
148 | that you do not use a "v" prefix. You MUST NOT use a mixture of "v"
149 | prefixed and non-prefixed tags. Pick one form and stick to it.
150 | 3. If the version string is hard-coded into the code-base, you MUST create a
151 | "version bump" commit which changes the hard-coded version string of the
152 | project.
153 | 4. When using version bump commits, the release tag MUST be placed on the
154 | version bump commit.
155 | 5. If you are not using a release branch, then the release tag, and if
156 | relevant the version bump commit, MUST be created directly on the master
157 | branch.
158 | 6. The version bump commit SHOULD have a commit message title of "Bump
159 | version to VERSION". For example, if the new version string is "2.11.4",
160 | the first line of the commit message SHOULD read: "Bump version to
161 | 2.11.4"
162 | 7. It is RECOMMENDED that release tags are lightweight tags, but you can
163 | OPTIONALLY use annotated tags if you want to include changelog
164 | information in the release tag itself.
165 | 8. If you use annotated release tags, the first line of the annotation
166 | SHOULD read "Release VERSION". For example for version "2.11.4" the first
167 | line of the tag annotation SHOULD read "Release 2.11.4". The second line
168 | MUST be blank, and the changelog MUST start on the third line.
169 | 7. Short-Term Release Branches
170 | 1. Any branch that has a name starting with "release-" SHOULD be referred to
171 | as a "release branch".
172 | 2. Any release branch which has a name ending with a specific version
173 | string, MUST be referred to as a "short-term release branch".
174 | 3. Use of short-term release branches are OPTIONAL, and intended to be used
175 | to create a specific versioned release.
176 | 4. A short-term release branch is RECOMMENDED if there is a lengthy
177 | pre-release verification process to avoid a code freeze on the master
178 | branch.
179 | 5. Short-term release branches MUST have a name of "release-VERSION". For
180 | example for version "2.11.4" the release branch name MUST be
181 | "release-2.11.4".
182 | 6. When using a short-term release branch to create a release, the release
183 | tag and if used, version bump commit, MUST be placed directly on the
184 | short-term release branch itself.
185 | 7. Only very minor changes should be performed on a short-term release
186 | branch directly. Any larger changes SHOULD be done in the master branch,
187 | and SHOULD be pulled into the release branch by rebasing it on top of the
188 | master branch the same way a change branch pulls in updates from its
189 | source branch.
190 | 8. After a release tag has been created, the release branch MUST be merged
191 | back into its source branch and then deleted. Typically the source branch
192 | will be the master branch.
193 | 8. Long-term Release Branches
194 | 1. Any release branch which has a name ending with a non-specific version
195 | string, MUST be referred to as a "long-term release branch". For example
196 | "release-2.11" is a long-term release branch, while "release-2.11.4" is a
197 | short-term release branch.
198 | 2. Use of long-term release branches are OPTIONAL, and intended for work on
199 | versions which are not currently part of the master branch. Typically
200 | this is useful when you need to create a new maintenance release for a
201 | older version.
202 | 3. A long-term release branch MUST have a name with a non-specific version
203 | number. For example a long-term release branch for creating new 2.9.x
204 | releases MUST be named "release-2.9".
205 | 4. Long-term release branches for maintenance releases of older versions
206 | MUST be created from the relevant release tag. For example if the master
207 | branch is on version 2.11.4 and there is a security fix for all 2.9.x
208 | releases, the latest of which is "2.9.7". Create a new branch called
209 | "release-2.9" from the "2.9.7" release tag. The security fix release will
210 | then end up being version "2.9.8".
211 | 5. To create a new release from a long-term release branch, you MUST follow
212 | the same process as a release from the master branch, except the
213 | long-term release branch takes the place of the master branch.
214 | 7. A long-term release branch should be treated with the same respect as the
215 | master branch. It is effectively the master branch for the release series
216 | in question. Meaning it MUST always be in a non-broken state, MUST NOT be
217 | force pushed to, etc.
218 | 9. Bug Fixes & Rollback
219 | 1. You MUST NOT under any circumstances force push to the master branch or
220 | to long-term release branches.
221 | 2. If a change branch which has been merged into the master branch is found
222 | to have a bug in it, the bug fix work MUST be done as a new separate
223 | change branch and MUST follow the same workflow as any other change
224 | branch.
225 | 3. If a change branch is wrongfully merged into master, or for any other
226 | reason the merge must be undone, you MUST undo the merge by reverting the
227 | merge commit itself. Effectively creating a new commit that reverses all
228 | the relevant changes.
229 | 10. Git Best Practices
230 | 1. All commit messages SHOULD follow the Commit Guidelines and format from
231 | the official git
232 | documentation:
233 |
234 | 2. You SHOULD never blindly commit all changes with "git commit -a". It is
235 | RECOMMENDED you use "git add -i" or "git add -p" to add individual
236 | changes to the staging area so you are fully aware of what you are
237 | committing.
238 | 3. You SHOULD always use "--force-with-lease" when doing a force push. The
239 | regular "--force" option is dangerous and destructive. More
240 | information:
241 |
242 | 4. You SHOULD understand and be comfortable with
243 | rebasing:
244 | 5. It is RECOMMENDED that you always do "git pull --rebase" instead of "git
245 | pull" to avoid unnecessary merge commits. You can make this the default
246 | behavior of "git pull" with "git config --global pull.rebase true".
247 | 6. It is RECOMMENDED that all branches be merged using "git merge --no-ff".
248 | This makes sure the reference to the original branch is kept in the
249 | commits, allows one to revert a merge by reverting a single merge commit,
250 | and creates a merge commit to mark the integration of the branch with
251 | master.
252 |
253 | FAQ
254 | ---
255 |
256 | ### Why use Common-Flow instead of Git Flow, and how does it differ?
257 |
258 | Common-Flow tries to be a lot less complicated than Git Flow by having fewer
259 | types of branches, and simpler rules. Normal day to day development doesn't
260 | really change much:
261 |
262 | - You create change branches instead of feature branches, without the need of a
263 | "feature/" or "change/" prefix in the branch name.
264 | - Change branches are typically created from and merged back into "master"
265 | instead of "develop".
266 | - Creating a release is done by simply creating a git tag, typically on the
267 | master branch.
268 |
269 | In detail, the main differences between Git Flow and Common-Flow are:
270 |
271 | - There is no "develop" branch, there is only a "master" branch which contains
272 | the latest work. In Git Flow the master branch effectively ends up just being
273 | a pointer to the latest release, despite the fact that Git Flow includes
274 | release tags too. In Common-Flow you just look at the tags to find the latest
275 | release.
276 | - There are no "feature" or "hotfix" branches, there's only "change"
277 | branches. Any branch that is not master and introduces changes is a change
278 | branch. Change branches also don't have a enforced naming convention, they
279 | just have to have a "descriptive name". This makes things simpler and allows
280 | more flexibility.
281 | - Release branches are available, but optional. Instead of enforcing the use of
282 | release branches like Git Flow, Common-Flow only recommends the use of release
283 | branches when it makes things easier. If creating a new release by tagging
284 | "master" works for you, great, do that.
285 |
286 | ### Why use Common-Flow instead of GitHub Flow, and how does it differ?
287 |
288 | Common-Flow is essentially GitHub Flow with the addition of a "Release" concept
289 | that uses tags. It also attempts to define how certain common tasks are done,
290 | like updating change/feature branches from their source branches for
291 | example. This is to help end arguments about how such things are done.
292 |
293 | If a deployment/release for you is just getting the latest code in the master
294 | branch out, without caring about bumping version numbers or anything, then
295 | GitHub Flow is a good fit for you, and you probably don't need the extras of
296 | Common-Flow.
297 |
298 | However if your deployments/releases have specific version numbers, then
299 | Common-Flow gives you a simple set of rules of how to create and manage
300 | releases, on top of what GitHub Flow already does.
301 |
302 | ### What does "descriptive name" mean for change branches?
303 |
304 | It means what it sounds like. The name should be descriptive, as in by just
305 | reading the name of the branch you should understand what the branch's purpose
306 | is and what it does. Here's a few examples:
307 |
308 | - add-2fa-support
309 | - fix-login-issue
310 | - remove-sort-by-middle-name-functionality
311 | - update-font-awesome
312 | - change-search-behavior
313 | - improve-pagination-performance
314 | - tweak-footer-style
315 |
316 | Notice how none of these have any prefixes like "feature/" or "hotfix/", they're
317 | not needed when branch names are properly descriptive. However there's nothing
318 | to say you can't use such prefixes if you want.
319 |
320 | You can also add ticket numbers to the branch name if your team/org has that as
321 | part of it's process. But it is recommended that ticket numbers are added to the
322 | end of the branch name. The ticket number is essentially metadata, so put it at
323 | the end and out of the way of humans trying to read the descriptive name from
324 | left to right.
325 |
326 | ### How do we release an emergency hotfix when the master branch is broken?
327 |
328 | This should ideally never happen, however if it does you can do one of the
329 | following:
330 |
331 | - Review why the master branch is broken and revert the changes that caused the
332 | issues. Then apply the hotfix and release.
333 | - Or use a short-term release branch created from the latest release tag instead
334 | of the master branch. Apply the hotfix to the release branch, create a release
335 | tag on the release branch, and then merge it back into master.
336 |
337 | In this situation, it is recommended you try to revert the offending changes
338 | that's preventing a new release from master. But if that proves to be a
339 | complicated task and you're short on time, a short-term release branch gives you
340 | a instant fix to the situation at hand, and let's you resolve the issues with
341 | the master branch when you have more time on your hands.
342 |
343 | About
344 | -----
345 |
346 | The Git Common-Flow specification is authored
347 | by [Jim Myhrberg](https://jimeh.me/).
348 |
349 | If you'd like to leave feedback,
350 | please [open an issue on GitHub](https://github.com/jimeh/common-flow/issues).
351 |
352 | License
353 | -------
354 |
355 | [Creative Commons - CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
356 |
--------------------------------------------------------------------------------
/common-flow.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------