[Python-checkins] devguide (merge hg_transition -> default): Merge hg_transition into default
antoine.pitrou
python-checkins at python.org
Sat Mar 5 17:26:41 CET 2011
http://hg.python.org/devguide/rev/f8977b46f50e
changeset: 365:f8977b46f50e
parent: 358:540276f611ee
parent: 364:5e9711fbee48
user: Antoine Pitrou <solipsis at pitrou.net>
date: Sat Mar 05 17:26:11 2011 +0100
summary:
Merge hg_transition into default
files:
diff --git a/committing.rst b/committing.rst
--- a/committing.rst
+++ b/committing.rst
@@ -1,7 +1,7 @@
.. _committing:
-Committing Patches
-==================
+Committing and Pushing Changes
+==============================
Commit Messages
---------------
@@ -28,6 +28,74 @@
contributed to the resolution, it is good practice to credit them.
+Working with Mercurial_
+-----------------------
+
+As a core developer, the ability to push changes to the official Python
+repositories means you have to be more careful with your workflow:
+
+* You should not push new named branches to the main repository. You can
+ still use them in clones that you use for development of patches; you can
+ also push these branches to a **separate** public repository that will be
+ dedicated to maintenance of the work before the work gets integrated in the
+ main repository.
+
+* You should collapse changesets of a single feature or bugfix before pushing
+ the result to the main repository. The reason is that we don't want the
+ history to be full of intermediate commits recording the private history
+ of the person working on a patch. If you are using the rebase_ extension,
+ consider adding the ``--collapse`` option to ``hg rebase``. The collapse_
+ extension is another choice.
+
+Because of these constraints, it can be practical to use other approaches
+such as mq_ (Mercurial Queues), in order to maintain patches in a single
+local repository and to push them seamlessly when they are ready.
+
+
+.. _Mercurial: http://www.hg-scm.org/
+.. _mq: http://mercurial.selenic.com/wiki/MqExtension
+.. _rebase: http://mercurial.selenic.com/wiki/RebaseExtension
+.. _collapse: http://mercurial.selenic.com/wiki/CollapseExtension
+
+
+Minimal Configuration
+---------------------
+
+To use Mercurial as a committer (both of your and others' patches), you should
+set up some basic options in your `configuration file`_. Under Windows,
+TortoiseHg has a graphical settings dialog for most options, meaning you
+don't need to edit the file directly (it is still available in
+``%USERPROFILE%\Mercurial.ini``). Under other platforms, you must edit
+``~/.hgrc``.
+
+Here are the minimal options you need to activate:
+
+* your *username*: this setting defines the name that will be used when you
+ :ref:`commit <hg-commit>` changes. The usual convention is to also include
+ an e-mail contact address in there::
+
+ [ui]
+ username = Your Name <email at example.org>
+
+* *extended diffing*: this setting enables an `extended diff format`_
+ which is more useful than the standard unified diff format as it includes
+ metadata about file copies and permission bits::
+
+ [diff]
+ git = on
+
+Under Windows, you should also enable the `eol extension`_, which will
+fix any Windows-specific line endings your text editor might insert when you
+create or modify versioned files. The public repository has a hook which
+will reject all changesets having the wrong line endings, so enabling this
+extension on your local computer is in your best interest.
+
+
+.. _configuration file: http://www.selenic.com/mercurial/hgrc.5.html#files
+.. _extended diff format: http://www.selenic.com/mercurial/hg.1.html#diffs
+.. _eol extension: http://mercurial.selenic.com/wiki/EolExtension
+
+
Handling Other's Code
---------------------
@@ -48,40 +116,206 @@
ask on python-dev.
-Backporting
------------
+Forward-Porting
+---------------
+
If the patch is a bugfix and it does not break
-backwards-compatibility *at all*, then backport it to the branch(es) in
-maintenance mode. The easiest way to do this is to apply the patch in the
-development branch, commit, and then use svnmerge.py_ to backport the patch.
+backwards-compatibility *at all*, then it should be applied to the oldest
+branch applicable and forward-ported until it reaches the in-development branch
+of Python. A forward-port instead of a back-port is preferred as it allows the
+:abbr:`DAG (directed acyclic graph)` used by hg to work with the movement of
+the patch through the codebase instead of against it.
-For example, let us assume you just made commit 42 in the development branch
-and you want to backport it to the ``release31-maint`` branch. You would change
-your working directory to the maintenance branch and run the command::
+Even when porting an already committed patch, you should **still** check the
+test suite runs successfully before committing the patch to another branch.
- svnmerge.py merge -r 42
-This will try to apply the patch to the current branch and generate a commit
-message. You will need to revert ``Misc/NEWS`` and do a new entry (the file
-changes too much between releases to ever have a merge succeed). To do a
-reversion, you can either undo the changes::
+Porting Within a Major Version
+''''''''''''''''''''''''''''''
- svn revert Misc/NEWS
+Assume that Python 3.3 is the current in-development version of Python and that
+you have a patch that should also be applied to Python 3.2. To properly port
+the patch to both versions of Python, you should first apply the patch to
+Python 3.2::
-or you can manually fix the issue and tell svn the problem is resolved::
+ hg update 3.2
+ hg import --no-commit patch.diff
+ # Compile; run the test suite
+ hg commit
- svn resolved Misc/NEWS
+With the patch now committed, you want to merge the patch up into Python 3.3.
+This should be done *before* pushing your changes to hg.python.org, so that
+the branches are in sync on the public repository. Assuming you are doing
+all of your work in a single clone, do::
-Once your checkout is ready to be committed, do::
+ hg update default
+ hg merge 3.2
+ # Fix any conflicts; compile; run the test suite
+ hg commit
- svn ci -F svnmerge-commit-message.txt
+.. note::
+ *If the patch shouldn't be ported* from Python 3.2 to Python 3.3, you must
+ also make it explicit: merge the changes but revert them before committing::
-This will commit the backport along with using the commit message created by
-``svnmerge.py`` for you.
+ hg update default
+ hg merge 3.2
+ hg revert -a
+ hg commit
-If it turns out you do not have the time to do a backport, then at least leave
-the proper issue open on the tracker with a note specifying that the change
-should be backported so someone else can do it.
+ This is necessary so that the merge gets recorded; otherwise, somebody
+ else will have to make a decision about your patch when they try to merge.
+When you have finished your porting work (you can port several patches one
+after another in your local repository), you can push **all** outstanding
+changesets to hg.python.org::
-.. _svnmerge.py: http://svn.apache.org/repos/asf/subversion/trunk/contrib/client-side/svnmerge/svnmerge.py
+ hg push
+
+This will push changes in both the Python 3.2 and Python 3.3 branches to
+hg.python.org.
+
+
+Porting Between Major Versions
+''''''''''''''''''''''''''''''
+
+.. warning::
+ transplant always commits automatically. This breaks the
+ "run the test suite before committing" rule. We could advocate using
+ "hg qimport -r tip -P" afterwards but that would add another level of
+ complexity.
+
+To port a patch from, e.g., Python 3.2 to 2.7, you can use the `transplant
+extension`_. Assuming you first committed your changes as changeset
+``a7df1a869e4a`` in the 3.2 branch and have now :ref:`updated
+<hg-switch-branches>` your working copy to the 2.7 branch, do::
+
+ hg transplant a7df1a869e4a
+ # Compile; run the test suite
+ hg push
+
+
+Differences with ``svnmerge``
+'''''''''''''''''''''''''''''
+
+If you are coming from Subversion, you might be surprised by how Mercurial works.
+Despite its name, ``svnmerge`` is different from ``hg merge``: while ``svnmerge``
+allows to cherrypick individual revisions, ``hg merge`` can only merge whole
+lines of development in the repository's :abbr:`DAG (directed acyclic graph)`.
+Therefore, ``hg merge`` might force you to review outstanding changesets that
+haven't been merged by someone else yet.
+
+The way to avoid such situations is for everyone to make sure that they have
+merged their commits to the ``default`` branch. Just type::
+
+ $ hg branches
+ default 3051:a7df1a869e4a
+ 3.1 3012:b560997b365d (inactive)
+
+and check that all branches except ``default`` are marked *inactive*. This
+means there is no pending changeset to merge from these branches.
+
+
+.. _transplant extension: http://mercurial.selenic.com/wiki/TransplantExtension
+
+.. seealso::
+ `Merging work
+ <http://hgbook.red-bean.com/read/a-tour-of-mercurial-merging-work.html>`_,
+ in `Mercurial: The Definitive Guide <http://hgbook.red-bean.com/>`_.
+
+
+Long-term development of features
+---------------------------------
+
+If you want to work on a feature long-term (perhaps you're implementing a
+PEP), you will probably want to publish your work in a dedicated repository.
+The following instructions will help you do so on `hg.python.org
+<http://hg.python.org>`_'s infrastructure without requiring a lot of upload
+bandwidth.
+
+Go to the main repository's Web page (http://hg.python.org/cpython/); there
+you find a box labelled "server-side clone". Enter the relative path of the
+repository you want to create on the server, for example ``features/mywork``;
+and press the button. A new repository gets created on the server with all
+the changesets of the original repository (it will seem very fast; this is
+normal).
+
+You can now do a local clone of this repository on your disk::
+
+ $ hg clone ssh://hg@hg.python.org/features/mywork
+ $ cd mywork
+
+.. commented out: old instructions (without server-side cloning)
+
+ First create a public (empty) repository on hg.python.org::
+
+ $ hg init ssh://hg@hg.python.org/features/mywork
+
+ And do a local clone of that repository on your disk::
+
+ $ hg clone ssh://hg@hg.python.org/features/mywork
+ $ cd mywork
+
+ There, pull all the contents from the main repository, either from a local
+ clone::
+
+ $ hg pull ../cpython
+ $ hg update
+
+ or directly from the network (which is of course slower)::
+
+ $ hg pull http://hg.python.org/cpython
+ $ hg update
+
+It is recommended that you create a new `named branch`_ for your work, so as
+to easily track changes. That named branch will exist in your feature
+repository, but not in the main repository::
+
+ $ hg branch mywork
+ $ hg commit -m "Creating branch mywork"
+
+You can now work on your feature, commit changes as you will, and push them
+when desired::
+
+ $ hg push
+
+When you push them, they will land in the public repository at
+``ssh://hg@hg.python.org/features/mywork`` (or
+``http://hg.python.org/features/mywork`` for the read-only URL). Other
+people can clone the public repository and work on the code too.
+
+When you want to synchronize with CPython's upstream changes, you can pull
+from the main repository, either from its remote URL::
+
+ $ hg pull http://hg.python.org/cpython
+
+or from a local clone that you may have on your disk (which is of course
+faster)::
+
+ $ hg pull ../cpython
+
+and merge all new changes from branch ``default`` to branch ``mywork``::
+
+ $ hg branch
+ mywork
+ $ hg merge default
+
+
+.. _named branch: http://mercurial.selenic.com/wiki/NamedBranches
+
+
+Uploading a patch for review
+''''''''''''''''''''''''''''
+
+In this scheme, your work will probably consist of many commits (some of
+them merges). If you want to upload a patch for review somewhere, you need
+a single agregate patch. This is where having a dedicated named branch
+``mywork`` gets handy.
+
+First ensure that you have pulled *and merged* all changes from the main
+repository, as explained above. Then, assuming your :ref:`currently checked
+out branch <hg-current-branch>` is still ``mywork``, simply do::
+
+ $ hg diff -r default > mywork.patch
+
+This will write to ``mywork.patch`` all the changes between ``default`` and
+``mywork``.
diff --git a/communication.rst b/communication.rst
--- a/communication.rst
+++ b/communication.rst
@@ -31,7 +31,7 @@
it will get redirected here.
Python-checkins_ sends out an email for every commit to Python's various
-repositories (both svn.python.org and hg.python.org). All core developers
+repositories from http://hg.python.org. All core developers
subscribe to this list and are known to reply to these emails to make comments
about various issues they catch in the commit. Replies get redirected to
python-dev.
diff --git a/coredev.rst b/coredev.rst
--- a/coredev.rst
+++ b/coredev.rst
@@ -68,14 +68,11 @@
You can verify your commit access by looking at
http://www.python.org/dev/committers which lists all core developers by
-username. You can also execute the follow command and look for the word
-"success" in the output::
+username. If you want to practice, there is a `test repository
+<http://hg.python.org/test/>`_ where you can freely commit and push any
+changes you like::
- ssh pythondev at svn.python.org
-
-For Windows users using Pageant::
-
- c:\path\to\putty\plink.exe pythondev at svn.python.org
+ hg clone ssh://hg@hg.python.org/test/ hgtest
An entry in the :ref:`developers` should also be entered for you.
Typically the person who sponsored your application to become a core developer
@@ -110,12 +107,15 @@
are different than those for read-only checkouts as SSH is used instead of
HTTP.
-For the development branch, you can check out the development branch with::
+You can clone the repository (which contains all active branches) with::
- svn co svn+ssh://pythondev@svn.python.org/python/branches/py3k
+ hg clone ssh://hg@hg.python.org/cpython
-Make the appropriate changes to the URL to checkout maintenance branches by
-removing ``py3k`` and replacing it with the name of the branch you want.
+The default branch in that repository is the current development branch.
+You can of course switch your working copy to one of the maintenance branches,
+for example::
+
+ hg update 2.7
Responsibilities
diff --git a/devcycle.rst b/devcycle.rst
--- a/devcycle.rst
+++ b/devcycle.rst
@@ -44,12 +44,11 @@
The branch for the next minor version; it is under active development for
all kinds of changes: new features, semantic changes, performance improvements,
bug fixes. It can be :ref:`checked out <checkout>` from
-http://svn.python.org/projects/python/branches/py3k.
+http://hg.python.org/cpython#py3k.
Once a :ref:`final` release is made from the in-development branch (say, 3.2), a
-new :ref:`maintenance branch <maintbranch>` (e.g. ``release32-maint``)
-is created to host all bug fixing activity for further micro versions
-(3.2.1, 3.2.2, etc.).
+new :ref:`maintenance branch <maintbranch>` is created to host all bug fixing
+activity for further micro versions (3.2.1, 3.2.2, etc.).
.. _maintbranch:
diff --git a/faq.rst b/faq.rst
--- a/faq.rst
+++ b/faq.rst
@@ -6,92 +6,307 @@
Version Control
==================================
-Where can I learn about the version control system used, Subversion (svn)?
+Where can I learn about the version control system used, Mercurial (hg)?
-------------------------------------------------------------------------------
-`Subversion`_'s (also known as ``svn``) official web site is at
-http://subversion.apache.org/ . A book on Subversion published by
-`O'Reilly Media`_, `Version Control with Subversion`_, is available
+Mercurial_'s (also known as ``hg``) official web site is at
+http://mercurial.selenic.com/. A book on Mercurial published by
+`O'Reilly Media`_, `Mercurial: The Definitive Guide`_, is available
for free online.
-With Subversion installed, you can run the help tool that comes with
-Subversion to get help::
+With Mercurial installed, you can run the help tool that comes with
+Mercurial to get help::
- svn help
+ hg help
-The man page for ``svn`` is rather scant and not very helpful.
+The `man page`_ for ``hg`` provides a quick refresher on the details of
+various commands, but doesn't provide any guidance on overall
+workflow.
-.. _Subversion: http://subversion.apache.org/
+.. _Mercurial: http://mercurial.selenic.com/
.. _O'Reilly Media: http://www.oreilly.com/
-.. _Version Control with Subversion: http://svnbook.red-bean.com/
+.. _Mercurial\: The Definitive Guide: http://hgbook.red-bean.com/
+.. _man page: http://www.selenic.com/mercurial/hg.1.html
-What do I need to use Subversion?
+What do I need to use Mercurial?
-------------------------------------------------------------------------------
-.. _download Subversion: http://subversion.apache.org/packages.html
-
UNIX
'''''''''''''''''''
-First, you need to `download Subversion`_. Most UNIX-based operating systems
-have binary packages available. Also, most packaging systems also
-have Subversion available.
+First, you need to `download Mercurial`_. Most UNIX-based operating systems
+have binary packages available. Most package management systems also
+have native Mercurial packages available.
-If you have checkin rights, you need OpenSSH_. This is needed to verify
-your identity when performing commits.
+If you have push rights, you need OpenSSH_. This is needed to verify
+your identity when performing commits. As with Mercurial, binary packages
+are typically available either online or through the platform's package
+management system.
+.. _download Mercurial: http://mercurial.selenic.com/downloads/
.. _OpenSSH: http://www.openssh.org/
+
Windows
'''''''''''''''''''
-You have several options on Windows. One is to `download Subversion`_ itself
-which will give you a command-line version. Another option is to `download
-TortoiseSVN`_ which integrates with Windows Explorer.
+The recommended option on Windows is to `download TortoiseHg`_ which
+integrates with Windows Explorer and also bundles the command line client
+(meaning you can type ``hg`` in a DOS box). Note that most
+entries in this FAQ only cover the command line client in detail - refer
+to the TortoiseHg documentation for assistance with its graphical interface.
-If you have checkin rights, you will also need an SSH client.
-`Download PuTTY and friends`_ (PuTTYgen, Pageant, and Plink) for this. All
-other questions in this FAQ will assume you are using these tools.
+If you have push rights, you need to configure Mercurial to work with
+your SSH keys. For that, open your Mercurial configuration file
+(you can do so by opening the TortoiseHg configuration dialog and then
+clicking *"Edit File"*). In the ``[ui]`` section, add the following line::
-Once you have both Subversion and PuTTY installed you must tell Subversion
-where to find an SSH client. Do this by editing
-``%APPDATA%\Subversion\config`` to have the following
-section::
+ ssh = TortoisePlink.exe -ssh -2 -C -i C:\path\to\yourkey.ppk
- [tunnels]
- ssh="c:/path/to/putty/plink.exe" -T
+where ``C:\path\to\yourkey.ppk`` should be replaced with the actual path
+to your SSH private key.
-Change the path to be the proper one for your system. The ``-T``
-option prevents a pseudo-terminal from being created.
+.. note::
+ If your private key is in OpenSSH format, you must first convert it to
+ PuTTY format by loading it into `PuTTYgen`_.
-You can use Pageant to prevent from having to type in your password for your
-SSH 2 key constantly. If you prefer not to have another program running,
-you need to create a profile in PuTTY.
+.. _download TortoiseHg: http://tortoisehg.bitbucket.org/download/index.html
-Go to Session:Saved Sessions and create a new profile named
-``svn.python.org``. In Session:Host Name, enter ``svn.python.org``. In
-SSH/Auth:Private key file select your private key. In Connection:Auto-login
-username enter ``pythondev``.
-With this set up, paths are slightly different than most other settings in that
-the username is not required. Do take notice of this when choosing to check
-out a project!
+What's a working copy? What's a repository?
+-------------------------------------------
-.. _download TortoiseSVN: http://tortoisesvn.net/downloads
-.. _PuTTY: http://www.chiark.greenend.org.uk/~sgtatham/putty/
-.. _download PuTTY and friends: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
+Mercurial is a "distributed" version control system. This means that each
+participant, even casual contributors, download a complete copy (called a
+*clone*, since it is obtained by calling ``hg clone``) of the central
+repository which can be treated as a stand-alone repository for all purposes.
+That copy is called in the FAQ the *local repository*, to differentiate
+with any *remote repository* you might also interact with.
+But you don't modify files directly in the local repository; Mercurial doesn't
+allow for it. You modify files in what's called the *working copy* associated
+with your local repository: you also run compilations and tests there.
+Once you are satisfied with your changes, you can :ref:`commit them <hg-commit>`;
+committing records the changes as a new *revision* in the *local repository*.
-How do I update my working copy to be in sync with the repository?
+Changes in your *local repository* don't get automatically shared with the
+rest of the world. Mercurial ensures that you have to do so explicitly
+(this allows you to experiment quite freely with multiple branches of
+development, all on your private computer). The main commands for doing
+so are ``hg pull`` and ``hg push``.
+
+
+Which branches are in my local repository?
+------------------------------------------
+
+Typing ``hg branches`` displays the open branches in your local repository::
+
+ $ hg branches
+ default 68026:f12ef116dd10
+ 3.2 68025:cef92ee1a323
+ 2.7 68010:8174d00d0797
+ 3.1 67955:5be8b695ea86
+ 2.6 67287:5e26a860eded
+ 2.5 65464:e4ecac76e499
+
+
+Why are some branches marked "inactive"?
+----------------------------------------
+
+Assuming you get the following output::
+
+ $ hg branches
+ default 68042:8ff33af017ef
+ 3.2 68039:c17d7772c638 (inactive)
+
+This means all changesets in the "3.2" branch have been merged into the
+"default" branch (or any other branch, if such exists).
+
+
+.. _hg-current-branch:
+
+Which branch is currently checked out in my working copy?
+---------------------------------------------------------
+
+Use::
+
+ $ hg branch
+ default
+
+Or to get more information::
+
+ $ hg summary
+ parent: 68026:f12ef116dd10 tip
+ In FTP.close() method, make sure to also close the socket object, not only the file.
+ branch: default
+ commit: (clean)
+ update: (current)
+
+
+.. _hg-switch-branches:
+
+How do I switch between branches inside my working copy?
+--------------------------------------------------------
+
+Simply use ``hg update`` to checkout another branch in the current directory::
+
+ $ hg branch
+ default
+ $ hg update 3.2
+ 86 files updated, 0 files merged, 11 files removed, 0 files unresolved
+ $ hg branch
+ 3.2
+
+Adding the ``-v`` option to ``hg update`` will list all updated files.
+
+
+I want to keep a separate working copy per development branch, is it possible?
+------------------------------------------------------------------------------
+
+Just clone your local repository and update each clone to a different branch::
+
+ $ hg clone cpython py32
+ updating to branch default
+ 3434 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ cd py32
+ $ hg update 3.2
+ 86 files updated, 0 files merged, 11 files removed, 0 files unresolved
+
+The current branch in a working copy is "sticky": if you pull in some new
+changes, ``hg update`` will update to the head of the *current branch*.
+
+
+How do I link my local repository to a particular remote repository?
+-------------------------------------------------------------------------------
+
+Your local repository is linked by default to the remote repository it
+was *cloned* from. If you created it from scratch, however, it is not linked
+to any remote repository. In ``.hg/hgrc`` file for the local repository, add
+or modify the following section::
+
+ [paths]
+ default = ssh://hg@hg.python.org/devguide
+
+This example is for a local repository that mirrors the ``devguide`` repository
+on ``hg.python.org``. The same approach works for other remote repositories.
+
+Anywhere that ``<remote repository>`` is used in the commands in this
+FAQ, ``hg`` will use the default remote repository if you omit the parameter.
+
+
+How do I create a shorthand alias for a remote repository?
+-------------------------------------------------------------------------------
+
+In your global ``.hgrc`` file add a section similar to the following::
+
+ [paths]
+ dg = ssh://hg@hg.python.org/devguide
+
+This example creates a ``dg`` alias for the ``devguide`` repository
+on ``hg.python.org``. This allows "dg" to be entered instead of the
+full URL for commands taking a repository argument (e.g. ``hg pull dg`` or
+``hg outgoing dg``).
+
+Anywhere that ``<remote repository>`` is used in the commands in this
+FAQ, ``hg`` should accept an alias in place of a complete remote URL.
+
+
+How do I compare my local repository to a remote repository?
+-------------------------------------------------------------------------------
+
+To display the list of changes that are in your local repository, but not
+in the remote, use::
+
+ hg outgoing <remote repository>
+
+This is the list of changes that will be sent if you call
+``hg push <remote repository>``. It does **not** include any :ref:`uncommitted
+changes <hg-status>` in your working copy!
+
+Conversely, for the list of changes that are in the remote repository but
+not in the local, use::
+
+ hg incoming <remote repository>
+
+This is the list of changes that will be retrieved if you call
+``hg pull <remote repository>``.
+
+.. note::
+ In most daily use, you will work against the default remote repository,
+ and therefore simply type ``hg outgoing`` and ``hg incoming``.
+
+ In this case, you can also get a synthetic summary using
+ ``hg summary --remote``.
+
+
+How do I update my local repository to be in sync with a remote repository?
-------------------------------------------------------------------------------
Run::
- svn update
+ hg pull <remote repository>
-from the directory you wish to update. The directory and all its
-subdirectories will be updated.
+from the repository you wish to pull the latest changes into. Most of the
+time, that repository is a clone of the repository you want to pull from,
+so you can simply type::
+
+ hg pull
+
+This doesn't update your working copy, though. See below:
+
+
+How do I update my working copy with the latest changes?
+--------------------------------------------------------
+
+Do::
+
+ hg update
+
+This will update your working copy with the latest changes on the
+:ref:`current branch <hg-current-branch>`. If you had :ref:`uncommitted
+changes <hg-status>` in your working copy, they will be merged in.
+
+If you find yourself typing often ``hg pull`` followed by ``hg update``,
+be aware that you can combine them in a single command::
+
+ hg pull -u
+
+
+.. _hg-local-workflow:
+
+How do I apply a patch?
+-------------------------------------------------------------------------------
+
+If you want to try out or review a patch generated using Mercurial, do::
+
+ hg import --no-commit somework.patch
+
+This will apply the changes in your working copy without committing them.
+If the patch was not created by Mercurial (for example, a patch created by
+Subversion and thus lacking any ``a``/``b`` directory prefixes in the patch),
+add ``-p0`` to the above command.
+
+You can also use the ``patch`` program, but be aware that it does not
+understand the `extended diff format`_ used by Mercurial.
+
+If you want to work on the patch using mq_ (Mercurial Queues), type instead::
+
+ hg qimport somework.patch
+
+This will create a patch in your queue with a name that matches the filename.
+You can use the ``-n`` argument to specify a different name. To have the
+patch applied to the working copy, type::
+
+ hg qpush
+
+Finally, to delete the patch, first un-apply it if necessary using ``hg qpop``,
+then do::
+
+ hg qdelete somework.patch
+
+.. _extended diff format: http://www.selenic.com/mercurial/hg.1.html#diffs
+.. _mq: http://mercurial.selenic.com/wiki/MqExtension
How do I add a file or directory to the repository?
@@ -99,38 +314,54 @@
Simply specify the path to the file or directory to add and run::
- svn add PATH
+ hg add PATH
-Subversion will skip any directories it already knows about. But if
-you want new files that exist in any directories specified in ``PATH``, specify
-``--force`` and Subversion will check *all* directories for new files.
+If ``PATH`` is a directory, Mercurial will recursively add any files in that
+directory and its descendents.
-You will then need to run ``svn commit`` (as discussed in
-`How do I commit a change to a file?`_) to commit the file to the repository.
+If you want Mercurial to figure out by itself which files should be added
+and/or removed, just run::
+ hg addremove
+
+**Be careful** though, as it might add some files that are not desired in
+the repository (such as build products, cache files, or other data).
+
+You will then need to run ``hg commit`` (as discussed below) to commit
+the file(s) to your local repository.
+
+
+.. _hg-commit:
How do I commit a change to a file?
-------------------------------------------------------------------------------
-To have any changes to a file (which include adding a new file or deleting an
-existing one), you use the command::
+To commit any changes to a file (which includes adding a new file or deleting
+an existing one), you use the command::
- svn commit [PATH]
+ hg commit [PATH]
-Although ``PATH`` is optional, if PATH is omitted all changes
-in your local copy will be committed to the repository.
-**DO NOT USE THIS!!!** You should specify the specific files
-to be committed unless you are *absolutely* positive that
-*all outstanding modifications* are meant to go in this commit.
+``PATH`` is optional: if it is omitted, all changes in your working copy
+will be committed to the local repository. When you commit, be sure that all
+changes are desired by :ref:`reviewing them first <hg-status>`;
+also, when making commits that you intend to push to public repositories,
+you should **not** commit together unrelated changes.
To abort a commit that you are in the middle of, leave the message
empty (i.e., close the text editor without adding any text for the
-message). Subversion will confirm if you want to abort the commit.
+message). Mercurial will then abort the commit operation so that you can
+try again later.
-If you do not like the default text editor Subversion uses for
-entering commmit messages, you may specify a different editor
-in your Subversion config file with the
-``editor-cmd`` option in the ``[helpers]`` section.
+Once a change is committed to your local repository, it is still only visible
+by you. This means you are free to experiment with as many local commits
+you feel like.
+
+.. note::
+ If you do not like the default text editor Mercurial uses for
+ entering commmit messages, you may specify a different editor,
+ either by changing the ``EDITOR`` environment variable or by setting
+ a Mercurial-specific editor in your global ``.hgrc`` with the ``editor``
+ option in the ``[ui]`` section.
How do I delete a file or directory in the repository?
@@ -138,52 +369,96 @@
Specify the path to be removed with::
- svn delete PATH
+ hg remove PATH
-Any modified files or files that are not checked in will not be deleted
-in the working copy on your machine.
+This will remove the file or the directory from your working copy; you will
+have to :ref:`commit your changes <hg-commit>` for the removal to be recorded
+in your local repository.
-What files are modified locally in my working copy?
+.. _hg-status:
+
+What files are modified in my working copy?
-------------------------------------------------------------------------------
Running::
- svn status [PATH]
+ hg status
-will list any differences between your working copy and the repository. Some
+will list any pending changes in the working copy. These changes will get
+commited to the local repository if you issue an ``hg commit`` without
+specifying any path.
+
+Some
key indicators that can appear in the first column of output are:
-= ===========================
-A Scheduled to be added
-D Scheduled to be deleted
-M Modified locally
-? Not under version control
-= ===========================
+ = ===========================
+ A Scheduled to be added
+ R Scheduled to be removed
+ M Modified locally
+ ? Not under version control
+ = ===========================
+If you want a line-by-line listing of the differences, use::
-How do I find out what Subversion properties are set for a file or directory?
--------------------------------------------------------------------------------
+ hg diff
-::
- svn proplist PATH
-
-
-How do I revert a file I have modified back to the version in the respository?
+How do I revert a file I have modified back to the version in the repository?
-------------------------------------------------------------------------------
Running::
- svn revert PATH
+ hg revert PATH
-will change ``PATH`` to match the version in the repository, throwing away any
+will revert ``PATH`` to its version in the repository, throwing away any
changes you made locally. If you run::
- svn revert -R .
+ hg revert -a
-from the root of your local repository it will recursively restore everything
-to match up with the main server.
+from the root of your working copy it will recursively restore everything
+to match up with the repository.
+
+
+How do I find out which revisions need merging?
+-----------------------------------------------
+
+In unambiguous cases, Mercurial will find out for you if you simply try::
+
+ hg merge
+
+If that fails and Mercurial asks for explicit revisions, running::
+
+ hg heads
+
+will give you the list of branch heads in your local repository. If you are
+working only in a particular named branch, for example ``default``, do::
+
+ hg heads default
+
+to display the heads on that branch.
+
+
+How do I list the files in conflict after a merge?
+--------------------------------------------------
+
+Use::
+
+ hg resolve --list
+
+(abbreviated ``hg resolve -l``)
+
+
+How I mark a file resolved after I have resolved merge conflicts?
+-----------------------------------------------------------------
+
+Type::
+
+ hg resolve --mark <file path>
+
+(abbreviated ``hg resolve -m <file path>``)
+
+If you are sure you have resolved all conflicts, use ``hg resolve -am``.
How do I find out who edited or what revision changed a line last?
@@ -191,80 +466,70 @@
You want::
- svn blame PATH
+ hg annotate PATH
-This will output to stdout every line of the file along with what revision
-number last touched that line and who committed that revision. Since it is
-printed to stdout, you probably want to pipe the output to a pager::
+This will output to stdout every line of the file along with which revision
+last modified that line. When you have the revision number, it is then
+easy to :ref:`display it in detail <hg-log-rev>`.
- svn blame PATH | less
+.. _hg-log:
How can I see a list of log messages for a file or specific revision?
---------------------------------------------------------------------
-To see the log messages for a specific file, run::
+To see the history of changes for a specific file, run::
- svn log PATH
+ hg log -v [PATH]
-That will list all messages that pertain to the file specified in ``PATH``.
+That will list all messages of revisions which modified the file specified
+in ``PATH``. If ``PATH`` is omitted, all revisions are listed.
-If you want to view the log message for a specific revision, run::
+If you want to display line-by-line differences for each revision as well,
+add the ``-p`` option::
- svn log --verbose -r REV
+ hg log -vp [PATH]
-With ``REV`` substituted with the revision number. The ``--verbose`` flag
-should be used to get a listing of all files modified in that revision.
+.. _hg-log-rev:
+If you want to view the differences for a specific revision, run::
-How can I edit the log message of a committed revision?
+ hg log -vp -r <revision number>
+
+
+How can I see the changeset graph in my repository?
+---------------------------------------------------
+
+In Mercurial repositories, changesets don't form a simple list, but rather
+a graph: every changeset has one or two parents (it's called a merge changeset
+in the latter case), and can have any number of children.
+
+The graphlog_ extension is very useful for examining the structure of the
+changeset graph. It is bundled with Mercurial.
+
+Graphical tools, such as TortoiseHG, will display the changeset graph
+by default.
+
+.. _graphlog: http://mercurial.selenic.com/wiki/GraphlogExtension
+
+
+How do I undo the changes made in a recent commit?
-------------------------------------------------------------------------------
-Use::
+First, this should not happen if you take the habit of :ref:`reviewing changes
+<hg-status>` before committing them.
- svn propedit -r <revision> --revprop svn:log
+In any case, run::
-Replace ``<revision>`` with the revision number of the commit whose log message
-you wish to change.
+ hg backout <revision number>
+This will modify your working copy so that all changes in ``<revision number>``
+(including added or deleted files) are undone. You then need to :ref:`commit
+<hg-commit>` these changes so that the backout gets permanently recorded.
-How do I get a diff between the repository and my working copy for a file?
--------------------------------------------------------------------------------
-
-The diff between your working copy and what is in the repository can be had
-with::
-
- svn diff PATH
-
-This will work off the current revision in the repository. To diff your
-working copy with a specific revision, do::
-
- svn diff -r REV PATH
-
-Finally, to generate a diff between two specific revisions, use::
-
- svn diff -r REV1:REV2 PATH
-
-Notice the ``:`` between ``REV1`` and ``REV2``.
-
-
-How do I undo the changes made in a recent committal?
--------------------------------------------------------------------------------
-
-Assuming your bad revision is ``NEW`` and ``OLD`` is the equivalent of ``NEW
-- 1``, then run::
-
- svn merge -r NEW:OLD PATH
-
-This will revert *all* files back to their state in revision ``OLD``.
-The reason that ``OLD`` is just ``NEW - 1`` is you do not want files to be
-accidentally reverted to a state older than your changes, just to the point
-prior.
-
-Note: PATH here refers to the top of the checked out repository,
-not the full pathname to a file. PATH can refer to a different
-branch when merging from the head, but it must still be the top
-and not an individual file or subdirectory.
+.. note::
+ These instructions are for Mercurial 1.7 and higher. ``hg backout`` has
+ a slightly different behaviour in versions before 1.7.
How do I update to a specific release tag?
@@ -272,105 +537,34 @@
Run::
- svn list svn+ssh://pythondev@svn.python.org/python/tags
+ hg tags
-or visit::
+to get a list of tags. To update your working copy to a specific tag, use::
- http://svn.python.org/view/python/tags/
+ hg update <tag>
-to get a list of tags. To switch your current sandbox to a specific tag,
-run::
- svn switch svn+ssh://pythondev@svn.python.org/python/tags/r242
+How come feature XYZ isn't available in Mercurial?
+--------------------------------------------------
-To just update to the revision corresponding to that tag without changing
-the metadata for the repository, note the revision number corresponding to
-the tag of interest and update to it, e.g.::
+Mercurial comes with many bundled extensions which can be explicitly enabled.
+You can get a list of them by typing ``hg help extensions``. Some of these
+extensions, such as ``color``, can prettify output; others, such as ``fetch``
+or ``transplant``, add new Mercurial commands.
- svn update -r 39619
+There are also many `configuration options`_ to tweak various aspects of the
+command line and other Mercurial behaviour; typing `man hgrc`_ displays
+their documentation inside your terminal.
+In the end, please refer to the Mercurial `wiki`_, especially the pages about
+`extensions`_ (including third-party ones) and the `tips and tricks`_.
-Why should I use ``svn switch``?
--------------------------------------------------------------------------------
-If you picture each file/directory in Subversion as uniquely identified
-by a 2-space coordinate system [URL, revision] (given a checkout, you can
-use "svn info" to get its coordinates), then we can say that "svn up -r N"
-(for some revision number N) keeps the url unchanged and changes the
-revision to whatever number you specified. In other words, you get the
-state of the working copy URL at the time revision N was created. For
-instance, if you execute it with revision 39619 within the trunk working
-copy, you will get the trunk at the moment 2.4.2 was released.
-
-On the other hand, "svn switch" moves the URL: it basically "moves" your
-checkout from [old_URL, revision] to [new_URL, HEAD], downloading the
-minimal set of diffs to do so. If the new_URL is a tag URL
-(e.g. .../tags/r242), it means any revision is good, since nobody is going
-to commit into that directory (it will stay unchanged forever). So
-[/tags/r242, HEAD] is the same as any other [/tags/r242, revision] (assuming
-of course that /tags/r242 was already created at the time the revision was
-created).
-
-If you want to create a sandbox corresponding to a particular release tag,
-use svn switch to switch to [/tags/some_tag, HEAD] if you don't plan on
-doing modifications. On the other hand if you want to make modifications to
-a particular release branch, use svn switch to change to
-[/branches/some_branch, HEAD].
-
-(Written by Giovanni Bajo on python-dev.)
-
-
-How do I create a branch?
--------------------------
-
-The best way is to do a server-side copy by specifying the URL for the source
-of the branch, and the eventual destination URL for the new branch::
-
- svn copy SRC_URL DEST_URL
-
-You can then checkout your branch as normal. You will want to prepare your
-branch for future merging from the source branch so as to keep them in sync
-using svnmerge.py.
-
-
-How do I include an external svn repository (external definition) in the repository?
-------------------------------------------------------------------------------------
-
-Before attempting to include an external svn repository into Python's
-repository, it is important to realize that you can only include directories,
-not individual files.
-
-To include a directory of an external definition (external svn repository) as a
-directory you need to edit the ``svn:externals`` property on the root of the
-repository you are working with using the format of::
-
- local_directory remote_repositories_http_address
-
-For instance, to include Python's sandbox repository in the 'sandbox' directory
-of your repository, run ``svn propedit svn:externals .`` while in the root of
-your repository and enter::
-
- sandbox http://svn.python.org/projects/sandbox/trunk/
-
-in your text editor. The next time you run ``svn update`` it will pull in the
-external definition.
-
-
-How can I create a directory in the sandbox?
-------------------------------------------------------------------------------
-
-Assuming you have commit privileges and you do not already have a complete
-checkout of the sandbox itself, the easiest way is to use svn's ``mkdir``
-command::
-
- svn mkdir svn+ssh://pythondev@svn.python.org/sandbox/trunk/<directory>
-
-That command will create the new directory on the server. To gain access to
-the new directory you then checkout it out (substitute ``mkdir`` in the command
-above with ``checkout``).
-
-If you already have a complete checkout of the sandbox then you can just use
-``svn mkdir`` on a local directory name and check in the new directory itself.
+.. _man hgrc: http://www.selenic.com/mercurial/hgrc.5.html
+.. _wiki: http://mercurial.selenic.com/wiki/
+.. _extensions: http://mercurial.selenic.com/wiki/UsingExtensions
+.. _tips and tricks: http://mercurial.selenic.com/wiki/TipsAndTricks
+.. _configuration options: http://www.selenic.com/mercurial/hgrc.5.html
SSH
@@ -400,8 +594,8 @@
key to a file. Copy the section with the public key (using Alt-P) to a file;
that file now has your public key.
+.. _PuTTYgen: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
-.. _PuTTYgen: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
Is there a way to prevent from having to enter my password for my SSH 2 public key constantly?
------------------------------------------------------------------------------------------------
@@ -416,22 +610,32 @@
.. _KeyChain: http://www.gentoo.org/proj/en/keychain/
+
+.. _pageant:
+
Windows
'''''''''''''''''''
-Running Pageant_ will prevent you from having to type your password constantly.
+The Pageant program is bundled with TortoiseHg. You can find it in its
+installation directory (usually ``C:\Program Files (x86)\TortoiseHg\``);
+you can also `download it separately
+<http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_.
+
+Running Pageant will prevent you from having to type your password constantly.
If you add a shortcut to Pageant to your Autostart group and edit the shortcut
so that the command line includes an argument to your private key then Pageant
will load the key every time you log in.
-.. _Pageant: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
-
-Can I make check-ins from machines other than the one I generated the keys on?
+Can I make commits from machines other than the one I generated the keys on?
------------------------------------------------------------------------------
-Yes, all you need is to make sure that the machine you want to check
-in code from has both the public and private keys in the standard
+You can :ref:`make commits <hg-commit>` from any machine, since they will be
+recorded in your *local repository*.
+
+However, to push these changes to the remote server, you will need proper
+credentials. All you need is to make sure that the machine you want to
+push changes from has both the public and private keys in the standard
place that ssh will look for them (i.e. ~/.ssh on Unix machines).
Please note that although the key file ending in .pub contains your
user name and machine name in it, that information is not used by the
diff --git a/grammar.rst b/grammar.rst
--- a/grammar.rst
+++ b/grammar.rst
@@ -62,6 +62,6 @@
* After everything's been checked in, you're likely to see a new
change to Python/Python-ast.c. This is because this
- (generated) file contains the svn version of the source from
+ (generated) file contains the hg version of the source from
which it was generated. There's no way to avoid this; you just
have to submit this file separately.
diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -33,7 +33,6 @@
faq
-
Quick Links
-----------
@@ -56,6 +55,8 @@
at once, but please do not skip around within the documentation as everything
is written assuming preceding documentation has been read.
+You can, *however*, read the :doc:`FAQ <faq>` at any point!
+
* :doc:`setup`
* Coding style guides
* `PEP 7`_ (Style Guide for C Code)
@@ -103,9 +104,9 @@
* `Firefox search engine plug-in`_
* Buildbots_
* Source code
- * `Browse online <http://svn.python.org/view/>`_
- * `Daily snapshot <http://svn.python.org/snapshots/>`_
- * `Daily OS X installer <http://python.org/dev/daily-dmg/>`_
+ * `Browse online <http://hg.python.org/>`_
+ * `Snapshot of py3k <http://hg.python.org/cpython/archive/tip.tar.bz2>`_
+ * `XXX Daily OS X installer <http://www.python.org/dev/daily-dmg/>`_
* Tool support
* :doc:`emacs`
* :doc:`gdb`
@@ -121,7 +122,7 @@
.. _buildbots: http://python.org/dev/buildbot/
.. _Firefox search engine plug-in: http://www.python.org/dev/searchplugin/
-.. _Misc directory: http://svn.python.org/view/python/branches/py3k/Misc/
+.. _Misc directory: http://hg.python.org/cpython/file/tip/Misc
.. _PEPs: http://www.python.org/dev/peps
.. _PEP 7: http://www.python.org/dev/peps/pep-0007
.. _PEP 8: http://www.python.org/dev/peps/pep-0008
diff --git a/patch.rst b/patch.rst
--- a/patch.rst
+++ b/patch.rst
@@ -7,6 +7,61 @@
Creating
--------
+Tool Usage
+''''''''''
+
+.. _mq-workflow:
+
+Mercurial allows for various workflows according to each person's or
+project's preference. We present here a very simple solution based on mq_
+(*Mercurial Queues*). You are welcome to use any approach you like (including
+a svn-like approach of simply never saving any changes you make to your working
+copy and using ``hg diff`` to create a patch). Usage of mq_ is merely a
+suggestion; it's a balance between being able to do everything needed
+while allowing for more powerful usage if desired in the future.
+
+First make sure that the extension has been turned on in your ``.hgrc`` or
+``Mercurial.ini`` file::
+
+ [extensions]
+ mq =
+
+You can verify this is working properly by running ``hg help mq``.
+
+Before you start modifying things in your working copy, type::
+
+ hg qnew mywork
+
+where ``mywork`` is a descriptive name for what you are going to work on.
+This will create a patch in your patch queue. Whenever you have reached a point
+that you want to save what you have done, run::
+
+ hg qrefresh
+
+This will update the patch to contain all of the changes you have made up to
+this point. If you have added or removed any file, use ``hg add`` or ``hg
+remove``, respectively, before running ``hg qrefresh``.
+
+Later on, we will explain :ref:`how to generate a patch <patch-generation>`.
+
+If you want to delete your changes irrevocably (either because they were
+committed, or they ended up uninteresting), use::
+
+ hg qpop mywork
+ hg qdelete mywork
+
+.. seealso::
+ For more advanced usage of mq, read the `mq chapter
+ <http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html>`_
+ of `Mercurial: The Definitive Guide <http://hgbook.red-bean.com/>`_.
+
+ Also, regardless of your workflow, refer to the :ref:`FAQ <faq>` for
+ :ref:`more information on using Mercurial <hg-local-workflow>`.
+
+.. _issue tracker: http://bugs.python.org
+.. _mq: http://mercurial.selenic.com/wiki/MqExtension
+
+
Preparation
'''''''''''
@@ -54,43 +109,29 @@
.. _Python Software Foundation: http://www.python.org/psf/
+.. _patch-generation:
+
Generation
''''''''''
To perform a quick sanity check on your patch, you can run::
- make patchcheck
+ make patchcheck
This will check and/or fix various common things people forget to do for
-patches.
+patches, such as adding any new files needed for the patch to work (note
+that not all checks apply to non-core developers).
-To create your patch, you should generate a unified diff from your checkout's
-top-level directory::
+Assume you are using the :ref:`mq approach <mq-workflow>` suggested earlier,
+first check that all your local changes have been recorded (using
+``hg qrefresh``), then type the following::
- svn diff > patch.diff
+ hg qdiff > mywork.patch
-If your work needs some new files to be added to the source tree, remember
-to ``svn add`` them before generating the patch::
-
- svn add Lib/newfile.py
- svn diff > patch.diff
-
-To apply a patch generated this way, do::
-
- patch -p0 < patch.diff
-
-If the developer is using something other than svn to manage their code (e.g.,
-Mercurial), you might have to use ``-p1`` instead of ``-p0``.
-
-To undo a patch, you can revert **all** changes made in your checkout::
-
- svn revert -R .
-
-.. note:: The ``patch`` program is not available by default under Windows.
- You can find it `here <http://gnuwin32.sourceforge.net/packages/patch.htm>`_,
- courtesy of the `GnuWin32 <http://gnuwin32.sourceforge.net/>`_ project.
- Also, you may find it necessary to add the "``--binary``" option when trying
- to apply Unix-generated patches under Windows.
+If you are using another approach, you probably need to find out the right
+invocation of ``hg diff`` for your purposes; see ``hg help diff`` and ``hg
+help revisions``. Just please make sure that you
+generate a **single, condensed** patch rather than a series of several changesets.
Submitting
diff --git a/setup.rst b/setup.rst
--- a/setup.rst
+++ b/setup.rst
@@ -3,10 +3,10 @@
Getting Set Up
==============
-These instructions cover how to get a source checkout and a compiled version of
-the CPython interpreter (CPython is the version of Python available from
-http://www.python.org/). It also gives an overview of the directory
-structure of a CPython checkout.
+These instructions cover how to get a working copy of the source code and a
+compiled version of the CPython interpreter (CPython is the version of Python
+available from http://www.python.org/). It also gives an overview of the
+directory structure of the CPython source code.
.. contents::
@@ -14,44 +14,43 @@
Version Control Setup
---------------------
-CPython is developed using `Subversion <http://subversion.tigris.org/>`_
-(commonly abbreviated svn, after the program name).
+CPython is developed using `Mercurial <http://hg-scm.org/>`_
+(commonly abbreviated hg, after the program name).
It is easily available for common Unix systems by way of the standard package
-manager; under Windows, you might want to use the `TortoiseSVN
-<http://tortoisesvn.net/>`_ graphical client.
+manager; under Windows, you might want to use the `TortoiseHg
+<http://tortoisehg.org/>`_ graphical client.
.. _checkout:
-Checking out the code
-----------------------
+Getting the Source Code
+-----------------------
-One should always work from a checkout of the CPython source code. While it may
-be tempting to work from the downloaded copy you already have installed on your
+One should always work from a working copy of the CPython source code.
+While it may
+be tempting to work from the copy of Python you already have installed on your
machine, it is very likely that you will be working from out-of-date code as
the Python core developers are constantly updating and fixing things in their
:abbr:`VCS`. It also means you will have better tool
support through the VCS as it will provide a diff tool, etc.
-To get a read-only checkout of CPython's source, you need to checkout the source
-code. To get a read-only checkout of
-the :ref:`in-development <indevbranch>` branch of Python, run::
+To get a working copy of the :ref:`in-development <indevbranch>` branch of
+CPython (core developers use a different URL as outlined in :ref:`coredev`),
+run::
- svn co http://svn.python.org/projects/python/branches/py3k
+ hg clone http://hg.python.org/cpython
-If you want a read-only checkout of an already-released version of Python,
-i.e., a version in :ref:`maintenance mode <maintbranch>`, run something
-like the following which gets you a checkout for Python 3.1::
+If you want a working copy of an already-released version of Python,
+i.e., a version in :ref:`maintenance mode <maintbranch>`, you can update your
+working copy. For instance, to update your working copy to Python 3.1, do::
- svn co http://svn.python.org/projects/python/branches/release31-maint
+ hg update 3.1
-To check out a version of Python other than 3.1, simply change the number in
-the above URL to the major/minor version (e.g., ``release27-maint`` for Python
-2.7).
+You will need to re-compile CPython when you do such an update.
-Do note that CPython will notice that it is being run from a source checkout.
-This means that it if you edit Python's source code in your checkout the
-changes will be picked up by the interpreter for immediate testing.
+Do note that CPython will notice that it is being run from a working copy.
+This means that it if you edit CPython's source code in your working copy the
+changes will be picked up by the interpreter for immediate use and testing.
Compiling (for debugging)
@@ -125,9 +124,9 @@
that can be run in-place; ``./python`` on most machines (and what is used in
all examples), ``./python.exe`` on OS X (when on a case-insensitive filesystem,
which is the default). There is absolutely no need to install your built copy
-of Python! The interpreter will realize it is being run directly out of a
-checkout and thus use the files found in the checkout. If you are worried you
-might accidentally install your checkout build, you can add
+of Python! The interpreter will realize where it is being run from
+and thus use the files found in the working copy. If you are worried
+you might accidentally install your working copy build, you can add
``--prefix=/dev/null`` to the configuration step.
.. _issue tracker: http://bugs.python.org
diff --git a/triaging.rst b/triaging.rst
--- a/triaging.rst
+++ b/triaging.rst
@@ -190,6 +190,10 @@
* ``r<number>``, ``rev<number>``, ``revision <number>`` links to the Subversion
revision ``<number>``.
+.. TODO update that last item to the format choosed for Mercurial: [CSET]
+ - check that [CSET] works
+ - check that rNUMBER links to the hglookup application
+
Reporting Issues About the Tracker
----------------------------------
--
Repository URL: http://hg.python.org/devguide
More information about the Python-checkins
mailing list