Add the stable/default entry.
Changes
--- a/.hgignore Sat May 01 00:19:01 2010 -0400
+++ b/.hgignore Mon May 17 18:28:09 2010 -0400
@@ -6,3 +6,4 @@
deploy/
deploy_tmp/
backups/
+*.swp
--- a/content/blog/2010/02/mercurial-workflows-branch-as-needed.html Sat May 01 00:19:01 2010 -0400
+++ b/content/blog/2010/02/mercurial-workflows-branch-as-needed.html Mon May 17 18:28:09 2010 -0400
@@ -40,7 +40,7 @@
[TOC]
-"Branch as Needed" In a Nutshell
+"Branch as Needed" in a Nutshell
--------------------------------
The general idea of this workflow is that you don't worry about branching
@@ -146,4 +146,4 @@
complicated branching workflows in the future. If you have any specific
examples you think I should write about please let me know!
-{% endblock %}
\ No newline at end of file
+{% endblock %}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/content/blog/2010/05/mercurial-workflows-stable-default.html Mon May 17 18:28:09 2010 -0400
@@ -0,0 +1,164 @@
+{% extends "_post.html" %}
+
+{% hyde
+ title: "Mercurial Workflows: Stable & Default"
+ snip: "Part 2 of several."
+ created: 2010-05-17 18:27:00
+ categories: ["programming"]
+%}
+
+{% block article %}
+
+This entry is the second in my series describing various Mercurial workflows.
+The [first][branch-as-needed] describes the simplest one: branching only
+when necessary.
+
+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.
+
+[branch-as-needed]: /blog/2010/02/mercurial-workflows-branch-as-needed.html
+
+[TOC]
+
+"Stable and Default" in a Nutshell
+----------------------------------
+
+The general idea of this workflow is that you keep two branches: `default` and
+`stable`.
+
+* **`default`** is the branch where new features and functionality are added.
+* **`stable`** is where bug fixes are added, as well as documentation improvements
+ that don't pertain to new features.
+
+Each time you make a bug fix in `stable` you merge it into `default`, so
+`default` is always a superset of `stable`.
+
+Periodically (whenever you're ready for a "major release") you'll merge
+`default` into `stable` so new features can be included in releases.
+
+[Mercurial][] itself [uses][hg-branches] this workflow for development, so it
+can scale well to projects of moderate to large size.
+
+[Mercurial]: http://hg-scm.org/
+[hg-branches]: http://selenic.com/repo/hg/branches/
+
+Branch Setup
+------------
+
+To get started using this workflow you'll need to create a `stable` named
+branch:
+
+ :::console
+ hg branch stable
+ hg commit -m "Create the stable branch."
+
+Once you do this users of your project can clone the `stable` 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:
+
+ :::console
+ hg clone http://bitbucket.org/you/yourproject#stable
+
+This will clone your project's repository and include only changesets on the
+`stable` branch (and any of their ancestors).
+
+Making Changes
+--------------
+
+The goal of this workflow is to do all non-bugfix development on the `default`
+branch. Pure bug fixes should go on the `stable` branch so `stable` stays as,
+well, "stable" as possible.
+
+Users that want to live on the bleeding edge of development can use the
+`default` branch of your project. Hopefully your project has some users that
+are willing to work with `default` and inform you of bugs found with the new
+functionality you add to it.
+
+Whenever you make a change to `stable` you'll want to merge it into `default`
+so that `default` always remains a superset of `stable`. This makes `default`
+as stable as it can possibly be. It also makes it easier to merge `default`
+back into stable whenever you're ready for a major release.
+
+Here's an example of how your repository's graph will end up looking:
+
+
+
+Notice how each time some changes are made on `stable` they're merged to
+`default`.
+
+Releasing Major Versions
+------------------------
+
+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
+`default` branch, so when you're ready to do this you'll merge `default` into
+`stable`.
+
+Because your project has more `stable` 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.
+
+Tagging Releases
+----------------
+
+Any decent project should tag releases. This lets users easily use a version
+of your project that they know works.
+
+Wondering how to decide when to tag releases, and what to use for the tags?
+The [semantic versioning][semver] specification is a great guide that makes it
+easy for your users to know (in a broad sense) what each release changes.
+
+In a nutshell, tags in a semantically versioned project work like this:
+
+* Tags are of the form "v[MAJOR].[MINOR].[BUGFIX]"
+* Tags with a major version of "0" make no guarantees about anything. They are
+ used for alpha/beta versions of the project.
+* An increase in the bugfix version of a project means "bugs were fixed."
+* An increase in the minor version of a project means "functionality has been
+ added without breaking backwards compatibility."
+* An increase in the major version of a project means "backwards compatibility
+ has been broken."
+
+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:
+
+* When you fix a bug on the `stable` branch, increment the bugfix version on
+ `stable` and merge `stable` into `default`.
+* When you add new functionality and are ready to release it to the public,
+ merge `default` into stable and increment the minor version of `stable`.
+* When you're ready for a backwards-incompatible release, merge `default` into
+ stable and increment the major version of `stable`.
+
+The problem with this is that `default` never has any version tags. However,
+this probably isn't a big deal because users of `default` are those that want
+to live on the bleeding edge of your project and aren't as concerned with
+stability.
+
+[semver]: http://semver.org/
+
+Why Default and Stable Instead of Default and Dev?
+--------------------------------------------------
+
+In the workflow I've described there are two branches: `default` and `stable`.
+You might be wondering why `default` is used for new development and the
+"stable" branch is relegated to a named branch.
+
+The reason is that `default` will typically have many, many more changesets
+added to it than `stable`, and so making the "development" branch the default
+makes it easier on the developers.
+
+There is absolutely *nothing* wrong with making `default` the "stable" branch
+and creating a `dev` 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.
+
+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 *not* overly concerned with bug
+fixes.
+
+It's up to you to decide which version you want to use.
+
+{% endblock %}
Binary file media/images/blog/2010/05/default-stable-example.png has changed
