├── docs ├── images │ ├── merge-to-pu.png │ ├── topichistory.png │ ├── creating-a-topic.png │ ├── topicgraduation.png │ └── integrationhistory.png ├── useful-commands.adoc ├── concepts-summary.adoc └── task-oriented-primer.adoc ├── .editorconfig ├── LICENSE └── README.adoc /docs/images/merge-to-pu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rocketraman/gitworkflow/HEAD/docs/images/merge-to-pu.png -------------------------------------------------------------------------------- /docs/images/topichistory.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rocketraman/gitworkflow/HEAD/docs/images/topichistory.png -------------------------------------------------------------------------------- /docs/images/creating-a-topic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rocketraman/gitworkflow/HEAD/docs/images/creating-a-topic.png -------------------------------------------------------------------------------- /docs/images/topicgraduation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rocketraman/gitworkflow/HEAD/docs/images/topicgraduation.png -------------------------------------------------------------------------------- /docs/images/integrationhistory.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rocketraman/gitworkflow/HEAD/docs/images/integrationhistory.png -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*.adoc] 4 | indent_style = space 5 | indent_size = 2 6 | charset = utf-8 7 | end_of_line = lf 8 | insert_final_newline = true 9 | trim_trailing_whitespace = true 10 | max_line_length = 120 11 | -------------------------------------------------------------------------------- /docs/useful-commands.adoc: -------------------------------------------------------------------------------- 1 | = Gitworkflow: Useful Commands and Aliases 2 | :toc: macro 3 | :toclevels: 3 4 | 5 | toc::[] 6 | 7 | == Navigating History 8 | 9 | === Enhancing "git log" 10 | 11 | TODO 12 | 13 | * `lg` https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9#file-gitconfig-L3[alias] 14 | * `lgp` https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9#file-gitconfig-L6[alias] 15 | 16 | === Integration Branch History 17 | 18 | TODO 19 | 20 | === Topic History 21 | 22 | TODO 23 | 24 | == Branch Notes 25 | 26 | TODO 27 | 28 | * `branchnote` https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9#file-gitconfig-L63[alias] 29 | * `branchnoterm` https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9#file-gitconfig-L64[alias] 30 | 31 | == Understanding Current Topic State 32 | 33 | TODO 34 | 35 | * `topics` https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9#file-gitconfig-L21[alias] 36 | * `where` https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9#file-gitconfig-L67[alias] 37 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Raman Gupta 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /docs/concepts-summary.adoc: -------------------------------------------------------------------------------- 1 | = Gitworkflow: Concepts Summary 2 | :toc: macro 3 | 4 | toc::[] 5 | 6 | == Introduction 7 | 8 | An earlier article described https://hackernoon.com/how-the-creators-of-git-do-branches-e6fcc57270fb[Gitworkflow]. This 9 | document expands on some of the concepts in a shorter, more digestible form. 10 | 11 | == Concepts 12 | 13 | === Topic Branches 14 | 15 | Topic branches, sometimes called feature branches, are where almost all development happens. Topics represent something 16 | being worked on, almost always in a branch, like a bug fix, hot fix, or new functionality. 17 | 18 | Name topic branches according to some convention. A good one is your initials, a slash, the issue tracker ID, a dash, 19 | and a (very) brief description in camel-case e.g.: 20 | 21 | rg/SP-1234-NewFrobnik 22 | 23 | The initials ease communication by immediately identifying the owner. The issue and description are short but also 24 | provide useful context. 25 | 26 | By branching from `maint` or `master`, we have the flexibility to merge the topic into branches like `next` or `pu` 27 | because those branches will share the branch point as a common ancestor). 28 | 29 | If topic B depends on another topic A that has not yet graduated to `master`, topic A may be merged into topic B. This 30 | complicates interactive branch rebases so this should be avoided when possible, however if necessary, git should handle 31 | this situation without too much problem. 32 | 33 | Smaller bugfixes and features may be merged directly into `maint` or `master` without going through a stabilization 34 | period in `next` or `pu`. Changes on `maint` are merged upwards into `master`, and changes on `master` are merged 35 | upwards into `next` and `proposed` (though these branches are more often simply rewound and rebuilt). 36 | 37 | === Integration Branches 38 | 39 | The integration branches are described here. 40 | 41 | Stable releases are cut from `master`, beta or acceptance test releases from `next`, and alpha or preview releases from 42 | `pu`. `maint` simply represents fixes to the previous release. The most stable up-to-date code is on `master`. 43 | 44 | Integration branches are exactly like any other branch in git. What makes them “special” is solely in how we have 45 | defined their use. 46 | 47 | ==== master 48 | 49 | The `master` branch is: 50 | 51 | * the code that is most up-to-date and stable 52 | 53 | and it has the following properties: 54 | 55 | * when creating a named new release, it would come from `master` 56 | * in a continuous deployment scenario, production would always run the tip of `master` 57 | * usually deployed to production, released to users 58 | * at some point, the tip of `master` is tagged with vX.Y.0 59 | * the `maint` branch is always based on some commit on `master` 60 | * never rewound or rebased, *always safe to base topics on* 61 | ** you may want to add a check in your git server to ensure force push does not happen on this branch 62 | * new topics are almost always based on `master` 63 | * usually contains all of `maint` (and must before a new release, since otherwise there are changes currently in prod 64 | that won’t be included in the new release) 65 | 66 | ==== next 67 | 68 | The `next` branch is: 69 | 70 | * the code currently being developed and stabilized for release 71 | 72 | and it has the following properties: 73 | 74 | * code merged to `next` is generally in fairly good shape, though perhaps there are regressions or other non-obvious 75 | issues 76 | * usually deployed to a testing environment 77 | at the beginning of every development cycle, rewound to `master`, but otherwise never rewound 78 | * usually contains all of `master` i.e. usually based on the head of `master` 79 | * when a release is made, if a topic branch currently in `next` is not stable enough promotion to `master`, it is 80 | simply not merged to `master` -- instead, it is merged to the next iteration of `next` 81 | * may be rewound to `master` at any time, and rebuilt with topics still in `next` -- but usually after a release 82 | * it is *never* merged into any another branch 83 | * new topics are not usually based on `next` 84 | ** one exception: if a topic is not expected to be stable for the next release, and the creator understands that 85 | the branch will need to be rebased when `next` is rewound and rebuilt, this is ok and may result in fewer conflicts 86 | during future rebase than if the topic started from `master` 87 | 88 | ==== pu 89 | 90 | The `pu` branch is: 91 | * “proposed” updates for temporary analysis, experimentation, or initial testing/review of one or more features 92 | ** anything else that doesn’t yet belong in `next` 93 | 94 | and it has the following properties: 95 | 96 | * to test / provide early warning whether the unmerged topic branches integrate cleanly -- if not, some communication 97 | to coordinate changes on topics is necessary 98 | * may be rewound to `master` at any time -- but usually once every day or every second day 99 | * it is *never* merged into any another branch 100 | * new topics are not usually based on `pu` 101 | 102 | ==== maint (and maint-X.Y) 103 | 104 | The `maint` branch is: 105 | 106 | * code that is the newest maintained production release 107 | 108 | The `maint-X.Y` branches are: 109 | 110 | * code that are older, but still maintained, production releases 111 | 112 | and they have the following properties: 113 | 114 | * usually deployed directly into production, perhaps with some but not extensive testing elsewhere 115 | * after release of `vX.Y.0` is made, `maint` is set to that commit 116 | * releases of `vX.Y.n` are made from `maint` if `X.Y` is current, or `maint-X.Y` if `X.Y` is an older maintained release 117 | * never rewound or rebased, *always safe to base topics on* 118 | ** you may want to add a check in your git server to ensure force push does not happen on this branch, with an exception 119 | for when the `maint` branch is moved to the new tip of `master` after a release 120 | * hotfix topics are merged to `maint` directly 121 | * new topics may be based on `maint` (or `maint-X.Y`) if the fix in the topic needs to be applied to that older release 122 | * can be merged to `master` to propagate fixes forward 123 | 124 | == The Life of a Topic Branch in Gitworkflow 125 | 126 | Development on a topic branch might go something like the following. There are a lot of variations on this basic 127 | structure -- this is just an example. 128 | 129 | The following includes topic rebasing to produce a clean series of commits. However, this is not required by 130 | gitworkflow -- just enabled by it. 131 | 132 | . Create a topic branch starting from master 133 | . commit - commit - commit 134 | . Push to a remote branch as necessary to back up the work or facilitate discussions with colleagues 135 | . `merge --no-ff` topic to the `pu` integration branch (manually or scripted and scheduled) 136 | .. check for conflicts and do initial review/testing of `pu` build 137 | . Cleanup topic history with an interactive rebase 138 | . Force push to origin topic branch 139 | . `merge --no-ff` topic to a rebuilt `pu` integration branch (manually or scripted and scheduled) 140 | . Code review 141 | . Fix code review comments in separate commits 142 | .. Don't rebase to simplify work of reviewer's so they know what you have changed, but use `--squash` and `--fixup` 143 | liberally 144 | . After review is completed, interactively rebase the squash and fixup commits to cleanup the topic history 145 | .. Use `--autosquash` to apply the fixup/squash commits 146 | . `merge --no-ff` to the `next` integration branch 147 | . Test, validate and change the topic as necessary 148 | . Merge topic branch to `master` (when release done), tag `master` with release version 149 | . Remove the topic branch locally and remotely 150 | -------------------------------------------------------------------------------- /README.adoc: -------------------------------------------------------------------------------- 1 | = Gitworkflow 2 | :homepage: https://github.com/rocketraman/gitworkflows 3 | 4 | The https://git.kernel.org/pub/scm/git/git.git/[git.git] project, responsible for the creation and maintenance of the 5 | https://git-scm.com/[git] tool itself, uses a powerful workflow I call "gitworkflow", in deference to its creators 6 | and the https://git-scm.com/docs/gitworkflows[man page] in which it is described. 7 | 8 | I describe the advantages of this workflow, in comparison to the popular 9 | http://nvie.com/posts/a-successful-git-branching-model/[GitFlow] by Vincent Drieesen and Adam Ruka's 10 | http://endoflineblog.com/oneflow-a-git-branching-model-and-workflow[OneFlow] in a blog post titled 11 | https://medium.com/hackernoon/how-the-creators-of-git-do-branches-e6fcc57270fb[How the Creators of Git do Branching]. 12 | 13 | This repository is meant to be a place in which tools and documentation related to gitworkflow can be created. 14 | 15 | == TL;DR 16 | 17 | * link:./docs/concepts-summary.adoc[Concepts Summary] 18 | * link:./docs/task-oriented-primer.adoc[Task-Oriented Primer] 19 | * link:./docs/useful-commands.adoc[Useful Commands] 20 | 21 | == Key Advantages 22 | 23 | The key advantages gitworkflow over GitFlow and OneFlow all come from treating topics as first-class citizens, not just 24 | temporary placeholders for unfinished code. 25 | 26 | === Amazing History 27 | 28 | Gitworkflow presents a history that code historians, and conscientious developers can love. It can easily present both 29 | summary (e.g. "show me all the topics merged into a release") and highly detailed views (e.g. "show me all the commits 30 | related to a topic"). 31 | 32 | A graph of a specific topic's history contains all of that topics commits, not interspersed with other topics: 33 | 34 | image:docs/images/topichistory.png[Topic History] 35 | 36 | but all of that detail can be elided to understand what was merged at a high level: 37 | 38 | image:docs/images/integrationhistory.png[Integration History] 39 | 40 | (both examples from the git.git repository) 41 | 42 | === Continuous Integration, Done Right 43 | 44 | Ever struggled with the decision about when to merge a topic branch to the main branch (`develop` in GitFlow / `master` 45 | everywhere else)? 46 | 47 | With GitFlow and OneFlow, in order to get the benefit of 48 | https://martinfowler.com/articles/continuousIntegration.html[Continuous Integration], you have to either test each topic 49 | branch in isolation, OR you have to merge it to the main line. Testing the topic in isolation, well, tests in isolation, 50 | which is "continuous", but isn't "integration". Waiting to merge until the topic is "done" means you can only test it 51 | along with other work that is also "done". This is "integration", but it isn't "continuous". 52 | 53 | This tension exists between "continuous" and "integration" because in most non-trivial projects, topics don't have a 54 | binary done/not done state: they are almost always a work in progress, with their stability being an analog continuum, 55 | not a digital value. We really want to do "continuous integration" of topics, even before they are considered "done" 56 | (i.e. released). 57 | 58 | With gitworkflow, the stability level of a topic is explicit -- and we can do true "continuous integration" of all the 59 | unreleased alpha-quality topics merged together to create an "alpha" release, all the unreleased beta-quality topics 60 | merged to create a "beta" release, and lastly all of the released topics. 61 | 62 | The early "continuous integration" of topics before they are "done" allows identification of conflicting work on 63 | different topics early in their development, prompting the right conversations and coordination between devs at the 64 | right time. 65 | 66 | ==== Make Your Topics Great 67 | 68 | Gitworkflow allows the alpha and beta-quality integration branches to be rewound and rebuild. This property allows 69 | topics to be massaged via interactive rebase until they form a series of easily understandable and reviewable chunks of 70 | work. With other flows, this is only an option until the topic is considered "done" and is merged to the main line for 71 | CI and user testing. Gitworkflow removes the limitation that a topic branch cannot be interactively rebased after it has 72 | been merged for CI and user testing, and especially for alpha-quality topics, this would be expected by most team leads 73 | and code reviewers, rather than frowned on. 74 | 75 | === Flexibility 76 | 77 | Sometimes features take longer to develop than expected. Sometimes they don't work well with other work in progress and 78 | need to be thrown away and a new approach taken. Sometimes everyone thinks they are "done", but they don't test well or 79 | they cause regressions. 80 | 81 | In most flows, this code is already on the main line of development. It has to be reverted (which can be easy or hard 82 | depending on the flow and the method used to merge the topic). 83 | 84 | In contrast, Gitworkflow defines a range of stability levels that the code "graduates" through, from raw unfinished code 85 | ("alpha") to code ready for testing ("beta") to code ready for release. Code can spend as much time as it needs to at 86 | each of these "levels", and when code is merged to the main line, it is production-ready. Thus gitworkflow supports 87 | continuous deployment scenarios as well. 88 | 89 | Gitworkflow allows you to define your own stability levels if you wish: add or remove integration branches as necessary. 90 | 91 | == Main Insights 92 | 93 | One key insight that makes gitworkflow work over flows like GitFlow and OneFlow is that: git is smarter than your 94 | average source control system. Topics don't have to be merged _only into the branch they were started from_, which seems 95 | to be the implicit or explicit assumption most flow authors make. In git, the topic can be merged _into any branch that 96 | it shares a common ancestor with_. 97 | 98 | This means that topic branches can be merged to multiple integration branches, each with a different purpose 99 | corresponding to the stability levels defined above. 100 | 101 | A related insight is that topics can be merged into other topics to explicitly deal with conflicts and encode 102 | dependencies. 103 | 104 | A second key insight is that, when topics are first-class citizens, early integration branches are just ephemeral 105 | placeholders for various combinations of topics, and can easily be recreated (rewind and rebuild). The integration 106 | branches are therefore unimportant and don't need to be a limiting factor for work on topics, such as rebasing, and 107 | we are free to experiment with moving topics in and out of them. 108 | 109 | The third key insight is that merge commits -- the ability to explicitly join two lines of development -- offer the 110 | ability to accomplish all of the above, as well as to continue to track topic history, long after the topic is no longer 111 | being developed, making code history spelunking great. 112 | 113 | == Disadvantages 114 | 115 | Gitworkfow is more complicated, and harder to understand than most (probably all) other flows. It requires more 116 | understanding of git concepts and capabilities. It offers significant powerful capabilities to complex multi-dimensional 117 | products with a team of developers, but does have more "overhead" in the sense of multiple things to track and 118 | understand. This means that: 119 | 120 | * Gitworkflow should not be used without significant team maturity using, or willingness to learn, git, and 121 | * Gitworkflow is serious overkill for trivial or one-man projects (but these might be a good place to try it out). 122 | 123 | == Interested in Learning More? 124 | 125 | === Documentation 126 | 127 | * link:./docs/concepts-summary.adoc[Concepts Summary] 128 | * link:./docs/task-oriented-primer.adoc[Task-Oriented Primer] 129 | * link:./docs/useful-commands.adoc[Useful Commands] 130 | 131 | === Questions? 132 | 133 | Feel free to ask questions about gitworkflow in the https://github.com/rocketraman/gitworkflow/issues[issues] of this 134 | repository. Please prefix your issue subject with `[Q]`. 135 | 136 | === The Gitworfkow Awesome List 137 | 138 | A curated list of related external articles and documentation. 139 | 140 | ==== Git.git Documentation 141 | 142 | All of the following are git.git resources by the git.git team. 143 | 144 | * "Managing Branches" in man page https://git-scm.com/docs/gitworkflows[gitworkflows(7)] 145 | * "How various branches are used" in git.git https://github.com/git/git/blob/efc912b23335434674bcfda8199077f8dfa5d6f0/MaintNotes#L144[MaintNotes] 146 | * "The Policy" in git.git https://github.com/git/git/blob/v2.13.0/Documentation/howto/maintain-git.txt#L35[maintain-git.txt] 147 | 148 | ==== Articles and Blog Posts 149 | 150 | * https://hackernoon.com/how-the-creators-of-git-do-branches-e6fcc57270fb[How the Creators of Git do Branching] by Raman Gupta 151 | 152 | == TODOs 153 | 154 | * Document useful commands with gitworkflow e.g. history spelunking, topic status, etc. 155 | ** Integrate and document aliases in https://gist.github.com/rocketraman/1fdc93feb30aa00f6f3a9d7d732102a9 156 | * Add more detail to link:./docs/concepts-summary.adoc[Concepts Summary] 157 | * Lots of work in link:./docs/task-oriented-primer.adoc[Task-Oriented Primer] 158 | * Lots of work in link:./docs/useful-commands.adoc[Useful Commands] 159 | -------------------------------------------------------------------------------- /docs/task-oriented-primer.adoc: -------------------------------------------------------------------------------- 1 | = Gitworkflow: A Task-Oriented Primer 2 | :toc: macro 3 | :toclevels: 3 4 | 5 | toc::[] 6 | 7 | == Introduction 8 | 9 | An earlier article described https://hackernoon.com/how-the-creators-of-git-do-branches-e6fcc57270fb[Gitworkflow]. This 10 | document goes into more details, focusing on a task-oriented visual presentation to make using gitworkflow as simple as 11 | possible. 12 | 13 | == Concepts 14 | 15 | See link:./concepts-summary.adoc[Concepts Summary] 16 | 17 | == Tasks 18 | 19 | All of the below summaries given using the git command line. Learn it! 20 | 21 | === Developers 22 | 23 | ==== Creating and Developing a Topic 24 | 25 | Topics are usually created by branching from `master`. Sometimes, from `maint`. 26 | 27 | *Question*: Is this topic eventually going to be merged to the existing release? 28 | 29 | * If *yes*, then branch from `master` 30 | * If *no*, then branch from `maint` 31 | 32 | WARNING: Never commit directly to `next` or `pu` without a topic branch -- these changes will be lost. 33 | 34 | Brush up on these commands and concepts: 35 | 36 | * git https://git-scm.com/docs/git-checkout[checkout] -b 37 | * git https://git-scm.com/docs/git-commit[commit] 38 | * git https://git-scm.com/docs/git-rebase[rebase] -i 39 | * git https://git-scm.com/docs/git-push[push] 40 | 41 | ===== Examples 42 | 43 | Create a new topic branch from `master` (see the link:./concepts-summary.adoc[Concepts Summary] for a good naming 44 | convention): 45 | 46 | (master) $ git checkout -b topic-branch 47 | 48 | Switched to a new branch 'topic-branch' 49 | 50 | (topic-branch) $ 51 | 52 | Now develop your topic, committing as you go. Write good commit messages. Use git rebase to make an easily reviewable 53 | series of commits. 54 | 55 | Once your branch is ready for a review (or simply to back it up), push it to the server: 56 | 57 | (topic-branch) $ git push --set-upstream origin topic-branch 58 | 59 | You can continue to work on this branch, and use git push to make your changes visible for code review. 60 | 61 | If you have long-running development of a feature, you will probably fall behind the `master` branch. If your branch has 62 | not been merged to another branch (e.g., `next`) yet, you can rebase/replay your changes on top of the latest `master` 63 | using 64 | 65 | (topic-branch) $ git rebase master 66 | 67 | You can continue to interactively rebase a topic to make an easily reviewable series of commits until your branch has 68 | been merged to `next`. After that, generally only push new commits to your branch (you can still rebase new commits 69 | locally before pushing to the remote). 70 | 71 | (topic-branch) $ git rebase -i master 72 | 73 | ===== Visualization 74 | 75 | Result of branching from `master` and committing twice: 76 | 77 | image:images/creating-a-topic.png[image] 78 | 79 | (https://codepen.io/rocketraman/pen/VbdOXd[https://codepen.io/rocketraman/pen/VbdOXd]) 80 | 81 | ==== Depending on Another Topic 82 | 83 | Oh oh, you need to develop some work that depends on another topic that has not yet been merged to `master`. Do not 84 | base your work on `next`. Instead, create your topic and merge the other topic into it. This explicitly records the 85 | dependency relationship between the topics, and puts the commit resolutions (if any) on the right branch. 86 | 87 | Brush up on these commands and concepts: 88 | 89 | * git https://git-scm.com/docs/git-merge[merge] --no-ff 90 | 91 | ===== Examples 92 | 93 | Branch `my-topic` depends on `frob-topic` 94 | 95 | (my-topic) $ git merge --no-ff frob-topic 96 | 97 | ===== Visualization 98 | 99 | TODO 100 | 101 | === Release Managers 102 | 103 | The following tasks are useful to understand for everyone, but especially people who take on the role of release 104 | managers (releasing to testing and prod environments). 105 | 106 | [[TopicStabilizationMergeToPu]] 107 | ==== Topic Stabilization on Proposed 108 | 109 | A topic is stabilized by first merging into `pu` (or "proposed updates"). The topic may be very raw and will probably 110 | cause regressions or have other problems in its current state. Merging to `pu` provides opportunity for early feedback 111 | on these problems, and also identifies topics that are conflicting so that the relevant devs can communicate and 112 | determine a strategy. 113 | 114 | Brush up on these commands and concepts: 115 | 116 | * git https://git-scm.com/docs/git-merge[merge] --no-ff 117 | * git https://git-scm.com/docs/git-revert[revert] -m 1 118 | 119 | Topics merged to `pu` can still be interactively rebased. Therefore `pu` can always be rewound to `master` (or to just 120 | before the rebased topic was merged), and everything from that point forward merged again ("rewind and rebuild"). 121 | Alternatively, the existing topic merge(s) can be reverted, and then the rebased topic merged again. 122 | 123 | NOTE: When pushing `pu` back to the server, if there is a conflict because someone else pushed a change to `pu` at 124 | the same time, do not do a merge pull. Instead, fetch `pu`, reset-hard to `origin/pu`, and then merge the topic 125 | branch again. This keeps the history of the integration branch when viewed with `--first-parent` clean. 126 | 127 | ===== Examples 128 | 129 | ``` 130 | $ git checkout pu 131 | (pu) $ git merge --no-ff topic-branch 132 | ``` 133 | 134 | ===== Visualization 135 | 136 | Result of merging `ai/foo-1` and `ai/bar-1` into `pu`: 137 | 138 | image:images/merge-to-pu.png[image] 139 | 140 | (https://codepen.io/rocketraman/pen/oWyRmM[https://codepen.io/rocketraman/pen/oWyRmM]) 141 | 142 | ==== Topic Graduation to Next 143 | 144 | A topic will generally be merged to `next` once technical and code reviews are complete, and perhaps some initial 145 | testing via `pu` has been done. The topic may cause regressions or have other issues that may still need to be solved. 146 | This generally represents all the development that is “done”, but will likely require more stabilization to fix 147 | regressions or other issues based on user testing in a UAT environment. 148 | 149 | A topic will spend as much time on `next` as necessary to stabilize the topic code. 150 | 151 | From this point forward, the topic is generally not rebased -- only new commits are pushed to it, and merged to `next` 152 | as necessary. However, this is not a hard-and-fast rule (see <> for techniques to deal 153 | with a rebased topic branch previously merged). 154 | 155 | See <> for the commands and concepts used. 156 | 157 | NOTE: When pushing `next` back to the server, if there is a conflict because someone else pushed a change to `next` at 158 | the same time, do not do a merge pull. Instead, fetch `next`, reset-hard to `origin/next`, and then merge the topic 159 | branch again. This keeps the history of the integration branch when viewed with `--first-parent` clean. 160 | 161 | ===== Tools 162 | 163 | TODO: Link to script to rebuild `next` based on topics currently in `next` 164 | 165 | ===== Examples 166 | 167 | ``` 168 | $ git checkout next 169 | (next) $ git merge --no-ff topic-branch 170 | ``` 171 | 172 | ===== Visualization 173 | 174 | TODO 175 | 176 | ==== Topic Graduation to Master 177 | 178 | We expect to merge a topic to `master` as soon as that topic is considered stable via testing on `next`. 179 | 180 | Not every commit on `master` (topic merges) need to form a “release”. In addition, even commits to `master` that *do* 181 | form a release are not necessarily deployed to production. The `master` branch does represent our latest “best” code, 182 | and will generally be run in production environments. 183 | 184 | ===== Examples 185 | 186 | TODO 187 | 188 | ===== Visualization 189 | 190 | In the following, `0.1` is the current release. Two separate features, developed by Bob, called `bob/feature-1` and 191 | `bob/feature-2` were initially merged into `next`. When `bob/feature-1` was merged, release `0.2-beta-1` was created. 192 | After `bob/feature-2` was merged, release `0.2-beta-2` was created. Lastly, both of these topics graduated, and were 193 | merged to `master` for release as `0.2`. 194 | 195 | image:images/topicgraduation.png[Topic Graduation to Master] 196 | 197 | (https://codepen.io/rocketraman/pen/mxayJw[https://codepen.io/rocketraman/pen/mxayJw]) 198 | 199 | ==== Create a Release 200 | 201 | Verify that `maint` contains no commits that are also not present in `master`: 202 | 203 | $ git log master..maint 204 | 205 | should return nothing. If it returns one or more commits, merge `maint` into `master` to preserve any maintenance 206 | changes in future releases. 207 | 208 | ``` 209 | $ git checkout master 210 | (master) $ git merge maint 211 | ``` 212 | 213 | Tag the latest (or a specific) version on `master` as a “release”. 214 | 215 | ``` 216 | $ git checkout master 217 | (master) $ git tag -a “v2.7.0” v2.7.0 218 | ``` 219 | 220 | Copy the existing maintenance branch: 221 | 222 | ``` 223 | $ git checkout `maint` 224 | (maint) $ git branch maint-2.6.4 225 | ``` 226 | 227 | Update the current maintenance branch: 228 | 229 | ``` 230 | $ git checkout maint 231 | (maint) $ git merge --ff-only master 232 | (maint) $ git push origin maint 233 | ``` 234 | 235 | NOTE: If the merge fails because the branch cannot be fast-forwarded, then it is possible some fixes on `maint` were 236 | missed in the feature release, and are not on `master`. This will not happen if the content of the branches was 237 | verified as per the earlier instructions. 238 | 239 | You will likely now wish to <> and <>. 240 | 241 | ===== Examples 242 | 243 | TODO 244 | 245 | ===== Visualization 246 | 247 | TODO 248 | 249 | [[RewindRebuildNext]] 250 | ==== Rewind and Rebuild next 251 | 252 | `next` may be rewound and rebuilt from `master` as often as needed. This will normally happen after a release. 253 | 254 | Brush up on these commands and concepts: 255 | 256 | * git https://git-scm.com/docs/git-reset[reset] --hard master 257 | * git https://git-scm.com/docs/git-merge[merge] --no-ff 258 | * git https://git-scm.com/blog/2010/03/08/rerere.html[rerere] 259 | * See also alias git mb ("merge branch") when working with remote branches 260 | 261 | The commands above may be used to semi-automate this process so that it can be run often -- once a day, or even as 262 | needed. 263 | 264 | A rebuild of `pu` might be needed if one or more topics have been rebased. This is relatively easy to semi-automate but 265 | some open source tooling would be useful. 266 | 267 | ===== Tools 268 | 269 | TODO: Link to script to rebuild `pu` based on topics currently in `pu` 270 | 271 | ===== Examples 272 | 273 | TODO 274 | 275 | ===== Visualization 276 | 277 | TODO 278 | 279 | [[RewindRebuildPu]] 280 | ==== Rewind and Rebuild pu 281 | 282 | `pu` may be rewound and rebuilt from `master` as often as needed. This will normally happen after a release. 283 | 284 | A rebuild of `pu` might also be needed if one or more topics have been rebased. This is relatively easy to semi-automate 285 | but some open source tooling would be useful. 286 | 287 | TIP: A CI system may be configured to do this on an hourly or daily basis, automatically rewinding `pu` and merging in 288 | all pending topics, building, and testing the result. This is a great way to catch conflicts between topics early. 289 | 290 | Brush up on these commands and concepts: 291 | 292 | * git https://git-scm.com/docs/git-reset[reset] --hard master 293 | * git https://git-scm.com/docs/git-merge[merge] --no-ff 294 | * git https://git-scm.com/blog/2010/03/08/rerere.html[rerere] 295 | * See also alias git mb ("merge branch") when working with remote branches 296 | 297 | ===== Tools 298 | 299 | TODO: Link to script to rebuild `pu` based on topics currently in `pu` 300 | 301 | ===== Examples 302 | 303 | TODO 304 | 305 | ===== Visualization 306 | 307 | TODO 308 | --------------------------------------------------------------------------------