Skip to content

replace master with main #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
spitfiredd wants to merge 1 commit into
base: master
Choose a base branch
from
Open

replace master with main #12

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ <h2>

<p>I travel all over the place teaching Git to people and nearly every class and workshop I've done recently has asked me what I think about <a href="http://nvie.com/posts/a-successful-git-branching-model/">git-flow</a>. I always answer that I think that it's great - it has taken a system (Git) that has a million possible workflows and documented a well tested, flexible workflow that works for lots of developers in a fairly straightforward manner. It has become something of a standard so that developers can move between projects or companies and be familiar with this standardized workflow.</p>

<p>However, it does have its issues. I have heard a number of opinions from people along the lines of not liking that new feature branches are started off of <code>develop</code> rather than <code>master</code>, or the way it handles hotfixes, but those are fairly minor.</p>
<p>However, it does have its issues. I have heard a number of opinions from people along the lines of not liking that new feature branches are started off of <code>develop</code> rather than <code>main</code>, or the way it handles hotfixes, but those are fairly minor.</p>

<p>One of the bigger issues for me is that it's more complicated than I think most developers and development teams actually require. It's complicated enough that a big <a href="https://github.com/nvie/gitflow">helper script</a> was developed to help enforce the flow. Though this is cool, the issue is that it cannot be enforced in a Git GUI, only on the command line, so the only people who have to learn the complex workflow really well, because they have to do all the steps manually, are the same people who aren't comfortable with the system enough to use it from the command line. This can be a huge problem.</p>

Expand All @@ -55,30 +55,30 @@ <h3>
<p>So, what is GitHub Flow? </p>

<ul>
<li>Anything in the <code>master</code> branch is deployable</li>
<li>To work on something new, create a descriptively named branch off of <code>master</code> (ie: <code>new-oauth2-scopes</code>)</li>
<li>Anything in the <code>main</code> branch is deployable</li>
<li>To work on something new, create a descriptively named branch off of <code>main</code> (ie: <code>new-oauth2-scopes</code>)</li>
<li>Commit to that branch locally and regularly push your work to the same named branch on the server</li>
<li>When you need feedback or help, or you think the branch is ready for merging, open a <a href="http://help.github.com/send-pull-requests/">pull request</a>
</li>
<li>After someone else has reviewed and signed off on the feature, you can merge it into master</li>
<li>Once it is merged and pushed to 'master', you can and <em>should</em> deploy immediately</li>
<li>After someone else has reviewed and signed off on the feature, you can merge it into main</li>
<li>Once it is merged and pushed to 'main', you can and <em>should</em> deploy immediately</li>
</ul><p>That is the entire flow. It is very simple, very effective and works for fairly large teams - GitHub is 35 employees now, maybe 15-20 of whom work on the same project (github.com) at the same time. I think that most development teams - groups that work on the same logical code at the same time which could produce conflicts - are around this size or smaller. Especially those that are progressive enough to be doing rapid and consistent deployments.</p>

<p>So, let's look at each of these steps in turn.</p>

<h4>
<a name="1---anything-in-the-master-branch-is-deployable" class="anchor" href="#1---anything-in-the-master-branch-is-deployable"><span class="octicon octicon-link"></span></a>#1 - anything in the master branch is deployable</h4>
<a name="1---anything-in-the-main-branch-is-deployable" class="anchor" href="#1---anything-in-the-main-branch-is-deployable"><span class="octicon octicon-link"></span></a>#1 - anything in the main branch is deployable</h4>

<p>This is basically the only hard <em>rule</em> of the system. There is only one branch that has any specific and consistent meaning and we named it <code>master</code>. To us, this means that it has been deployed or at the worst will be deployed within hours. It's incredibly rare that this gets rewound (the branch is moved back to an older commit to revert work) - if there is an issue, commits will be reverted or new commits will be introduced that fixes the issue, but the branch itself is almost never rolled back.</p>
<p>This is basically the only hard <em>rule</em> of the system. There is only one branch that has any specific and consistent meaning and we named it <code>main</code>. To us, this means that it has been deployed or at the worst will be deployed within hours. It's incredibly rare that this gets rewound (the branch is moved back to an older commit to revert work) - if there is an issue, commits will be reverted or new commits will be introduced that fixes the issue, but the branch itself is almost never rolled back.</p>

<p>The <code>master</code> branch is stable and it is always, always safe to deploy from it or create new branches off of it. If you push something to master that is not tested or breaks the build, you break the social contract of the development team and you normally feel pretty bad about it. Every branch we push has tests run on it and reported into the chat room, so if you haven't run them locally, you can simply push to a topic branch (even a branch with a single commit) on the server and wait for <a href="http://jenkins-ci.org/">Jenkins</a> to tell you if it passes everything.</p>
<p>The <code>main</code> branch is stable and it is always, always safe to deploy from it or create new branches off of it. If you push something to main that is not tested or breaks the build, you break the social contract of the development team and you normally feel pretty bad about it. Every branch we push has tests run on it and reported into the chat room, so if you haven't run them locally, you can simply push to a topic branch (even a branch with a single commit) on the server and wait for <a href="http://jenkins-ci.org/">Jenkins</a> to tell you if it passes everything.</p>

<p>You could have a <code>deployed</code> branch that is updated only when you deploy, but we don't do that. We simply expose the currently deployed SHA through the webapp itself and <code>curl</code> it if we need a comparison made.</p>

<h4>
<a name="2---create-descriptive-branches-off-of-master" class="anchor" href="#2---create-descriptive-branches-off-of-master"><span class="octicon octicon-link"></span></a>#2 - create descriptive branches off of master</h4>
<a name="2---create-descriptive-branches-off-of-main" class="anchor" href="#2---create-descriptive-branches-off-of-main"><span class="octicon octicon-link"></span></a>#2 - create descriptive branches off of main</h4>

<p>When you want to start work on anything, you create a descriptively named branch off of the stable <code>master</code> branch. Some examples in the GitHub codebase right now would be <code>user-content-cache-key</code>, <code>submodules-init-task</code> or <code>redis2-transition</code>. This has several advantages - one is that when you fetch, you can see the topics that everyone else has been working on. Another is that if you abandon a branch for a while and go back to it later, it's fairly easy to remember what it was.</p>
<p>When you want to start work on anything, you create a descriptively named branch off of the stable <code>main</code> branch. Some examples in the GitHub codebase right now would be <code>user-content-cache-key</code>, <code>submodules-init-task</code> or <code>redis2-transition</code>. This has several advantages - one is that when you fetch, you can see the topics that everyone else has been working on. Another is that if you abandon a branch for a while and go back to it later, it's fairly easy to remember what it was.</p>

<p>This is nice because when we go to the GitHub branch list page we can easily see what branches have been worked on recently and roughly how much work they have on them. </p>

Expand All @@ -91,7 +91,7 @@ <h4>
<h4>
<a name="3---push-to-named-branches-constantly" class="anchor" href="#3---push-to-named-branches-constantly"><span class="octicon octicon-link"></span></a>#3 - push to named branches constantly</h4>

<p>Another big difference from git-flow is that we push to named branches on the server constantly. Since the only thing we really have to worry about is <code>master</code> from a deployment standpoint, pushing to the server doesn't mess anyone up or confuse things - everything that is not <code>master</code> is simply something being worked on.</p>
<p>Another big difference from git-flow is that we push to named branches on the server constantly. Since the only thing we really have to worry about is <code>main</code> from a deployment standpoint, pushing to the server doesn't mess anyone up or confuse things - everything that is not <code>main</code> is simply something being worked on.</p>

<p>It also make sure that our work is always backed up in case of laptop loss or hard drive failure. More importantly, it puts everyone in constant communication. A simple 'git fetch' will basically give you a TODO list of what every is currently working on.</p>

Expand All @@ -107,7 +107,7 @@ <h4>
* [new branch] fi-signup -&gt; origin/fi-signup
2647a42..4d6d2c2 git-http-server -&gt; origin/git-http-server
* [new branch] knyle-style-commits -&gt; origin/knyle-style-commits
157d2b0..d33e00d master -&gt; origin/master
157d2b0..d33e00d main -&gt; origin/main
* [new branch] menu-behavior-act-i -&gt; origin/menu-behavior-act-i
ea1c5e2..dfd315a no-inline-js-config -&gt; origin/no-inline-js-config
* [new branch] svg-tests -&gt; origin/svg-tests
Expand All @@ -130,32 +130,32 @@ <h4>

<p><img src="https://img.skitch.com/20110831-j181q96hh7k8x2e1iuh38jsc8a.png" alt="more discussion"></p>

<p>Finally you can see that we're still in the trial phase - this is not a deployment ready branch yet, we use the Pull Requests to review the code long before we actually want to merge it into <code>master</code> for deployment.</p>
<p>Finally you can see that we're still in the trial phase - this is not a deployment ready branch yet, we use the Pull Requests to review the code long before we actually want to merge it into <code>main</code> for deployment.</p>

<p>If you are stuck in the progress of your feature or branch and need help or advice, or if you are a developer and need a designer to review your work (or vice versa), or even if you have little or no code but some screenshot comps or general ideas, you open a pull request. You can cc people in the GitHub system by adding in a <a href="https://github.com/username" class="user-mention">@username</a>, so if you want the review or feedback of specific people, you simply cc them in the PR message (as you saw Josh do above).</p>

<p>This is cool because the Pull Request feature let's you comment on individual lines in the unified diff, on single commits or on the pull request itself and pulls everything inline to a single conversation view.
It also let you continue to push to the branch, so if someone comments that you forgot to do something or there is a bug in the code, you can fix it and push to the branch, GitHub will show the new commits in the conversation view and you can keep iterating on a branch like that.</p>

<p>If the branch has been open for too long and you feel it's getting out of sync with the master branch, you can merge master into your topic branch and keep going. You can easily see in the pull request discussion or commit list when the branch was last brought up to date with the 'master'.</p>
<p>If the branch has been open for too long and you feel it's getting out of sync with the main branch, you can merge main into your topic branch and keep going. You can easily see in the pull request discussion or commit list when the branch was last brought up to date with the 'main'.</p>

<p><img src="https://img.skitch.com/20110831-q5dwhwk3dut7mdqm2kp7qwqu67.png" alt="master merge"></p>
<p><img src="https://img.skitch.com/20110831-q5dwhwk3dut7mdqm2kp7qwqu67.png" alt="main merge"></p>

<p>When everything is really and truly done on the branch and you feel it's ready to deploy, you can move on to the next step.</p>

<h4>
<a name="5---merge-only-after-pull-request-review" class="anchor" href="#5---merge-only-after-pull-request-review"><span class="octicon octicon-link"></span></a>#5 - merge only after pull request review</h4>

<p>We don't simply do work directly on <code>master</code> or work on a topic branch and merge it in when we think it's done - we try to get signoff from someone else in the company. This is generally a +1 or emoji or "<img class="emoji" title=":shipit:" alt=":shipit:" src="https://github.global.ssl.fastly.net/images/icons/emoji/shipit.png" height="20" width="20" align="absmiddle">" comment, but we try to get someone else to look at it.</p>
<p>We don't simply do work directly on <code>main</code> or work on a topic branch and merge it in when we think it's done - we try to get signoff from someone else in the company. This is generally a +1 or emoji or "<img class="emoji" title=":shipit:" alt=":shipit:" src="https://github.global.ssl.fastly.net/images/icons/emoji/shipit.png" height="20" width="20" align="absmiddle">" comment, but we try to get someone else to look at it.</p>

<p><img src="https://img.skitch.com/20110831-8gg3uhb14adjis43wa6swiinik.png" alt="shipit comment"></p>

<p>Once we get that, and the branch passes CI, we can merge it into master for deployment, which will automatically close the Pull Request when we push it.</p>
<p>Once we get that, and the branch passes CI, we can merge it into main for deployment, which will automatically close the Pull Request when we push it.</p>

<h4>
<a name="6---deploy-immediately-after-review" class="anchor" href="#6---deploy-immediately-after-review"><span class="octicon octicon-link"></span></a>#6 - deploy immediately after review</h4>

<p>Finally, your work is done and merged into the <code>master</code> branch. This means that even if you don't deploy it now, people will base new work off of it and the next deploy, which will likely happen in a few hours, will push it out. So since you really don't want someone else to push something that you wrote that breaks things, people tend to make sure that it really is stable when it's merged and people also tend to push their own changes.</p>
<p>Finally, your work is done and merged into the <code>main</code> branch. This means that even if you don't deploy it now, people will base new work off of it and the next deploy, which will likely happen in a few hours, will push it out. So since you really don't want someone else to push something that you wrote that breaks things, people tend to make sure that it really is stable when it's merged and people also tend to push their own changes.</p>

<p>Our campfire bot, hubot, can do deployments for any of the employees, so a simple:</p>

Expand Down