144 lines
9.3 KiB
HTML
144 lines
9.3 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html lang='en'><head><meta charset='utf-8' /><meta name='pinterest' content='nopin' /><link href='../../../../static/css/style.css' rel='stylesheet' type='text/css' /><link href='../../../../static/css/print.css' rel='stylesheet' type='text/css' media='print' /><title>Mercurial Workflows: Stable & Default / Steve Losh</title></head><body><header><a id='logo' href='https://stevelosh.com/'>Steve Losh</a><nav><a href='../../../index.html'>Blog</a> - <a href='https://stevelosh.com/projects/'>Projects</a> - <a href='https://stevelosh.com/photography/'>Photography</a> - <a href='https://stevelosh.com/links/'>Links</a> - <a href='https://stevelosh.com/rss.xml'>Feed</a></nav></header><hr class='main-separator' /><main id='page-blog-entry'><article><h1><a href='index.html'>Mercurial Workflows: Stable & Default</a></h1><p class='date'>Posted on May 17th, 2010.</p><p>This entry is the second in my series describing various Mercurial workflows.
|
||
|
|
The <a href="../../02/mercurial-workflows-branch-as-needed/index.html">first</a> describes the simplest one: branching only
|
||
|
|
when necessary.</p>
|
||
|
|
|
||
|
|
<p>If you're working on a larger project you might want something with a bit more
|
||
|
|
structure. This post is about the "stable and default" workflow.</p>
|
||
|
|
|
||
|
|
<ol class="table-of-contents"><li><a href="index.html#s1-stable-and-default-in-a-nutshell">"Stable and Default" in a Nutshell</a></li><li><a href="index.html#s2-branch-setup">Branch Setup</a></li><li><a href="index.html#s3-making-changes">Making Changes</a></li><li><a href="index.html#s4-releasing-major-versions">Releasing Major Versions</a></li><li><a href="index.html#s5-tagging-releases">Tagging Releases</a></li><li><a href="index.html#s6-why-default-and-stable-instead-of-default-and-dev">Why Default and Stable Instead of Default and Dev?</a></li></ol>
|
||
|
|
|
||
|
|
<h2 id="s1-stable-and-default-in-a-nutshell"><a href="index.html#s1-stable-and-default-in-a-nutshell">"Stable and Default" in a Nutshell</a></h2>
|
||
|
|
|
||
|
|
<p>The general idea of this workflow is that you keep two branches: <code>default</code> and
|
||
|
|
<code>stable</code>.</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><strong><code>default</code></strong> is the branch where new features and functionality are added.</li>
|
||
|
|
<li><strong><code>stable</code></strong> is where bug fixes are added, as well as documentation improvements
|
||
|
|
that don't pertain to new features.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Each time you make a bug fix in <code>stable</code> you merge it into <code>default</code>, so
|
||
|
|
<code>default</code> is always a superset of <code>stable</code>.</p>
|
||
|
|
|
||
|
|
<p>Periodically (whenever you're ready for a "major release") you'll merge
|
||
|
|
<code>default</code> into <code>stable</code> so new features can be included in releases.</p>
|
||
|
|
|
||
|
|
<p><a href="http://hg-scm.org/">Mercurial</a> itself <a href="http://selenic.com/repo/hg/branches/">uses</a> this workflow for development, so it
|
||
|
|
can scale well to projects of moderate to large size.</p>
|
||
|
|
|
||
|
|
<h2 id="s2-branch-setup"><a href="index.html#s2-branch-setup">Branch Setup</a></h2>
|
||
|
|
|
||
|
|
<p>To get started using this workflow you'll need to create a <code>stable</code> named
|
||
|
|
branch:</p>
|
||
|
|
|
||
|
|
<pre><code>hg branch stable
|
||
|
|
hg commit -m "Create the stable branch."</code></pre>
|
||
|
|
|
||
|
|
<p>Once you do this users of your project can clone the <code>stable</code> branch and be
|
||
|
|
confident that they're getting a relatively stable version of your code. To
|
||
|
|
clone a branch like this they would do something like:</p>
|
||
|
|
|
||
|
|
<pre><code>hg clone http://bitbucket.org/you/yourproject#stable</code></pre>
|
||
|
|
|
||
|
|
<p>This will clone your project's repository and include only changesets on the
|
||
|
|
<code>stable</code> branch (and any of their ancestors).</p>
|
||
|
|
|
||
|
|
<h2 id="s3-making-changes"><a href="index.html#s3-making-changes">Making Changes</a></h2>
|
||
|
|
|
||
|
|
<p>The goal of this workflow is to do all non-bugfix development on the <code>default</code>
|
||
|
|
branch. Pure bug fixes should go on the <code>stable</code> branch so <code>stable</code> stays as,
|
||
|
|
well, "stable" as possible.</p>
|
||
|
|
|
||
|
|
<p>Users that want to live on the bleeding edge of development can use the
|
||
|
|
<code>default</code> branch of your project. Hopefully your project has some users that
|
||
|
|
are willing to work with <code>default</code> and inform you of bugs found with the new
|
||
|
|
functionality you add to it.</p>
|
||
|
|
|
||
|
|
<p>Whenever you make a change to <code>stable</code> you'll want to merge it into <code>default</code>
|
||
|
|
so that <code>default</code> always remains a superset of <code>stable</code>. This makes <code>default</code>
|
||
|
|
as stable as it can possibly be. It also makes it easier to merge <code>default</code>
|
||
|
|
back into stable whenever you're ready for a major release.</p>
|
||
|
|
|
||
|
|
<p>Here's an example of how your repository's graph will end up looking:</p>
|
||
|
|
|
||
|
|
<p><img src="../../../../static/images/blog/2010/05/default-stable-example.png" alt="Sample Default and Stable Graph" title="Sample Default and Stable Graph"></p>
|
||
|
|
|
||
|
|
<p>Notice how each time some changes are made on <code>stable</code> they're merged to
|
||
|
|
<code>default</code>.</p>
|
||
|
|
|
||
|
|
<h2 id="s4-releasing-major-versions"><a href="index.html#s4-releasing-major-versions">Releasing Major Versions</a></h2>
|
||
|
|
|
||
|
|
<p>There will come a time when you're ready to release non-bugfix improvements to
|
||
|
|
your project to the general public. Non-bugfix improvements are made in the
|
||
|
|
<code>default</code> branch, so when you're ready to do this you'll merge <code>default</code> into
|
||
|
|
<code>stable</code>.</p>
|
||
|
|
|
||
|
|
<p>Because your project has more <code>stable</code> users than bleeding-edge users, you'll
|
||
|
|
probably get more bug reports than usual after you release a major version.
|
||
|
|
This is to be expected and you should be ready for it.</p>
|
||
|
|
|
||
|
|
<h2 id="s5-tagging-releases"><a href="index.html#s5-tagging-releases">Tagging Releases</a></h2>
|
||
|
|
|
||
|
|
<p>Any decent project should tag releases. This lets users easily use a version
|
||
|
|
of your project that they know works.</p>
|
||
|
|
|
||
|
|
<p>Wondering how to decide when to tag releases, and what to use for the tags?
|
||
|
|
The <a href="http://semver.org/">semantic versioning</a> specification is a great guide that makes it
|
||
|
|
easy for your users to know (in a broad sense) what each release changes.</p>
|
||
|
|
|
||
|
|
<p>In a nutshell, tags in a semantically versioned project work like this:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Tags are of the form "v[MAJOR].[MINOR].[BUGFIX]"</li>
|
||
|
|
<li>Tags with a major version of "0" make no guarantees about anything. They are
|
||
|
|
used for alpha/beta versions of the project.</li>
|
||
|
|
<li>An increase in the bugfix version of a project means "bugs were fixed."</li>
|
||
|
|
<li>An increase in the minor version of a project means "functionality has been
|
||
|
|
added without breaking backwards compatibility."</li>
|
||
|
|
<li>An increase in the major version of a project means "backwards compatibility
|
||
|
|
has been broken."</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Unfortunately this workflow makes it a bit more complicated to add semantic
|
||
|
|
versioning tags to your project. The rules for semantic tagging would work like
|
||
|
|
this:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>When you fix a bug on the <code>stable</code> branch, increment the bugfix version on
|
||
|
|
<code>stable</code> and merge <code>stable</code> into <code>default</code>.</li>
|
||
|
|
<li>When you add new functionality and are ready to release it to the public,
|
||
|
|
merge <code>default</code> into stable and increment the minor version of <code>stable</code>.</li>
|
||
|
|
<li>When you're ready for a backwards-incompatible release, merge <code>default</code> into
|
||
|
|
stable and increment the major version of <code>stable</code>.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The problem with this is that <code>default</code> never has any version tags. However,
|
||
|
|
this probably isn't a big deal because users of <code>default</code> are those that want
|
||
|
|
to live on the bleeding edge of your project and aren't as concerned with
|
||
|
|
stability.</p>
|
||
|
|
|
||
|
|
<h2 id="s6-why-default-and-stable-instead-of-default-and-dev"><a href="index.html#s6-why-default-and-stable-instead-of-default-and-dev">Why Default and Stable Instead of Default and Dev?</a></h2>
|
||
|
|
|
||
|
|
<p>In the workflow I've described there are two branches: <code>default</code> and <code>stable</code>.
|
||
|
|
You might be wondering why <code>default</code> is used for new development and the
|
||
|
|
"stable" branch is relegated to a named branch.</p>
|
||
|
|
|
||
|
|
<p>The reason is that <code>default</code> will typically have many, many more changesets
|
||
|
|
added to it than <code>stable</code>, and so making the "development" branch the default
|
||
|
|
makes it easier on the developers.</p>
|
||
|
|
|
||
|
|
<p>There is absolutely <em>nothing</em> wrong with making <code>default</code> the "stable" branch
|
||
|
|
and creating a <code>dev</code> branch for "unstable" changes. If your project rarely adds
|
||
|
|
new functionality but is more concerned with fixing bugs this version of the
|
||
|
|
workflow will obviously be better for you.</p>
|
||
|
|
|
||
|
|
<p>This version also has the added advantage of giving users that naively clone
|
||
|
|
your project (without a branch specified) the stable version. Since many users
|
||
|
|
don't bother to read instructions even when you provide them, there is a strong
|
||
|
|
argument for using it even when your project is <em>not</em> overly concerned with bug
|
||
|
|
fixes.</p>
|
||
|
|
|
||
|
|
<p>It's up to you to decide which version you want to use.</p>
|
||
|
|
</article></main><hr class='main-separator' /><footer><nav><a href='https://github.com/sjl/'>GitHub</a> ・ <a href='https://twitter.com/stevelosh/'>Twitter</a> ・ <a href='https://instagram.com/thirtytwobirds/'>Instagram</a> ・ <a href='https://hg.stevelosh.com/.plan/'>.plan</a></nav></footer></body></html>
|