Commits

Anonymous committed 812b850

initial draft

Comments (0)

Files changed (1)

+Title: hg-ibranch extension
+Author: André Felipe Dias <andref.dias at gmail dot com>
+Status: Draft
+Type: Mercurial Extension
+
+.. topic:: Collaboration
+
+    Both technical suggestions and grammar corrections are welcome!
+
+
+Abstract
+========
+
+The ``hg-ibranch`` is an extension that provides an ideal branching model to Mercurial.
+Basically, it combines named branches and bookmarks behaviors into a single one.
+The ibranch can be used to long and short-term branches,
+providing speed, flexibility and audit trail.
+
+There is no schema change. So, backward compatibility is granted.
+
+Motivation
+==========
+
+Currently, Mercurial has two different branching models: named branches and bookmarks.
+Bookmarks are used for short-term feature or topic branches
+whereas named branches are used for long-term branches.
+
+Bookmarks are fast and flexible.
+They are scalable and can be easily renamed and deleted.
+But they don't record an audit trail
+and this is the main reason why they aren't used in long-term branches.
+
+On the other hand,
+Named Branches creates an audit trail,
+but they cannot be renamed or deleted (only closed).
+There is also a performance penalty as the number of named branches increases.
+Thus, Named Branches are recommended for long-term branches only.
+
+Although bookmarks and named branches can coexist,
+they aren't really integrated.
+There are different sets of commands, options and synchronization policies that
+turns their use awkward and unnecessarily complex.
+A developer need to know too much detail to choose and operate both models simultaneously.
+
+Specification
+=============
+
+The original ``hg branch`` command is replaced by a new one with the following options::
+
+    hg branch [-d | -m NAME | [-r REV] [-b]] [NAME]
+
+    track a line of development with movable markers and audit trails
+
+        Branches are managed by pointers to certain revisions that move when committing,
+        leaving an audit trail behind. Branches can be renamed and deleted but these operations
+        actually change the internal pointers, maintaining the real branch id intact.
+
+        Branches are recommended to both short and long-term branches.
+
+        With no argument, show the current branch name. With one argument, set the
+        working directory branch name (the branch will not exist in the repository
+        until the next commit). Standard practice recommends that primary
+        development take place on the 'default' branch.
+
+        Use -r/--rev REV (where REV may be an existing branch name) to create a new branch from
+        a specific revision.
+
+        Use -b/--bookmark to create a new named head of an existing branch.
+
+        Use both -r/--rev REV and -b/--bookmark to create a new named head of an
+        existing branch from a specific revision
+
+        Use the command "hg update" to switch to an existing branch.
+
+    options:
+
+    -r, --rev REV       create a branch from revision REV
+    -d, --delete        delete a given branch name
+    -m, --rename NAME   rename a given branch name
+    -b, --bookmark      create a new named head to the current branch.
+
+    use "hg -v help branch" to show more info