PEP 385: more clarifications, notes on use, branching strategies.

pep-0385.txt

@@ -39,6 +39,12 @@ the following sections also propose discarding some of the older metadata.
 .. _hgsubversion: http://bitbucket.org/durin42/hgsubversion/
 
 
+Timeline
+========
+
+TBD; needs fully working hgsubversion and consensus on this document.
+
+
 Transition plan
 ===============
 
@@ -61,9 +67,13 @@ necessary tools to make named branches less painful (because they can be
 properly closed and closed heads are no longer considered in relevant cases).
 
 A disadvantage might be that the used clones will be a good bit larger (since
-they essentially contain all other branches as well). Perhaps it would be a 
-good idea to distinguish between feature branches (which would be done trough
-a separate clone) and release branches (which would be named).
+they essentially contain all other branches as well). This can me mitigated by
+keeping non-release (feature) branches in separate clones. Also note that it's
+still possible to clone a single named branch from a combined clone, by
+specifying the branch as in hg clone http://hg.python.org/main/#2.6-maint.
+Keeping the py3k history in a separate clone problably also makes sense.
+
+XXX To do: size comparison for selected separation scenarios.
 
 Converting branches
 -------------------
@@ -85,7 +95,8 @@ fact, full tags, but contain only a smaller subset of the repository. I think
 we should keep all release tags, and consider other tags for inclusion based
 on requests from the developer community. I'd like to consider unifying the
 release tag naming scheme to make some things more consistent, if people feel
-that won't create too many problems.
+that won't create too many problems. For example, Mercurial itself just uses
+'1.2.1' as a tag, where CPython would currently use r121.
 
 Author map
 ----------
@@ -173,3 +184,116 @@ A more or less stock hgwebdir installation should be set up. We might want to
 come up with a style to match the Python website. It may also be useful to
 build a quick extension to augment the URL rev parser so that it can also take
 r[0-9]+ args and come up with the matching hg revision.
+
+
+After migration
+===============
+
+Where to get code
+-----------------
+
+It needs to be decided where the hg repositories will live. I'd like to
+propose to keep the hgwebdir instance at hg.python.org. This is an accepted
+standard for many organizations, and an easy parallel to svn.python.org.
+The 2.7 (trunk) repo might live at http://hg.python.org/main/, for example,
+with py3k at http://hg.python.org/py3k/. For write access, developers will
+have to use ssh, which could be ssh://hg@hg.python.org/main/. A demo
+installation will be set up with a preliminary conversion so people can
+experiment and review; it can live at http://hg.python.org/example/.
+
+code.python.org was also proposed as the hostname. Personally, I think that
+using the VCS name in the hostname is good because it prevents confusion: it
+should be clear that you can't use svn or bzr for hg.python.org.
+
+hgwebdir can already provide tarballs for every changeset. I think this
+obviates the need for daily snapshots; we can just point users to tip.tar.gz
+instead, meaning they will get the latest. If desired, we could even use
+buildbot results to point to the last good changeset.
+
+Python-specific documentation
+-----------------------------
+
+hg comes with good built-in documentation (available through hg help) and a
+`wiki`_ that's full of useful information and recipes. In addition to that,
+the `parts of the developer FAQ`_ concerning version control will gain a
+section on using hg for Python development. Some of the text will be dependent
+on the outcome of debate about this PEP (for example, the branching strategy).
+
+ .. _wiki: http://www.selenic.com/mercurial/wiki/
+ .. _parts of the developer FAQ: http://www.python.org/dev/faq/#version-control
+
+Think first, commit later?
+--------------------------
+
+In recent history, old versions of Python have been maintained by a select
+group of people backporting patches from trunk to release branches. While
+this may not scale so well as the development pace grows, it also runs into
+some problems with the current crop of distributed versioning tools. These
+tools (I believe similar problems would exist for either git, bzr, or hg,
+though some may cope better than others) are based on the idea of a Directed
+Acyclic Graph (or DAG), meaning they keep track of relations of changesets.
+
+Mercurial itself has a stable branch which is a ''strict'' subset of the
+unstable branch. This means that generally all fixes for the stable branch
+get committed against the tip of the stable branch, then they get merged into
+the unstable branch (which already contains the parent of the new cset). This
+provides a largely frictionless environment for moving changes from stable to
+unstable branches. Mistakes, where a change that should go on stable goes on
+unstable first, do happen, but they're usually easy to fix. That can be done by
+copying the change over to the stable branch, then trivial-merging with
+unstable -- meaning the merge in fact ignores the parent from the stable
+branch).
+
+This strategy means a little more work for regular committers, because they
+have to think about whether their change should go on stable or unstable; they
+may even have to ask someone else (the RM) before committing. But it also
+relieves a dedicated group of committers of regular backporting duty, in
+addition to making it easier to work with the tool.
+
+Now would be a good time to consider changing strategies in this regard,
+although it would be relatively easy to switch to such a model later on.
+
+The future of Subversion
+------------------------
+
+What happens to the Subversion repositories after the migration? Since the svn
+server contains a bunch of repositories, not just the CPython one, it will
+probably live on for a bit as not every project may want to migrate or it
+takes longer for other projects to migrate. To prevent people from staying
+behind, we may want to remove migrated projects from the repository.
+
+Build identification
+--------------------
+
+Python currently provides the sys.subversion tuple to allow Python code to
+find out exactly what version of Python it's running against. The current
+version looks something like this:
+
+* ('CPython', 'tags/r262', '71600')
+* ('CPython', 'trunk', '73128M')
+
+Another value is returned from Py_GetBuildInfo() in the C API, and available
+to Python code as part of sys.version:
+
+* 'r262:71600, Jun  2 2009, 09:58:33'
+* 'trunk:73128M, Jun  2 2009, 01:24:14'
+
+I propose that the revision identifier will be the short version of hg's
+revision hash, for example 'dd3ebf81af43', augmented with '+' (instead of 'M')
+if the working directory from which it was built was modified. This mirrors
+the output of the hg id command, which is intended for this kind of usage.
+
+For the tag/branch identifier, I propose that hg will check for tags on the
+currently checked out revision, use the tag if there is one ('tip' doesn't
+count), and uses the branch name otherwise. sys.subversion becomes
+
+* ('CPython', '2.6.2', 'dd3ebf81af43')
+* ('CPython', 'default', 'af694c6a888c+')
+
+and the build info string becomes
+
+* '2.6.2:dd3ebf81af43, Jun  2 2009, 09:58:33'
+* 'default:af694c6a888c+, Jun  2 2009, 01:24:14'
+
+This reflects that the default branch in hg is called 'default' instead of
+Subversion's 'trunk', and reflects the proposed new tag format.