python
diff --git a/‎committing.rst
Lines changed: 2 additions & 2 deletions b/‎committing.rst
Lines changed: 2 additions & 2 deletions
diff --git a/‎communication.rst
Lines changed: 35 additions & 14 deletions b/‎communication.rst
Lines changed: 35 additions & 14 deletions
diff --git a/‎coredev.rst
Lines changed: 140 additions & 2 deletions b/‎coredev.rst
Lines changed: 140 additions & 2 deletions
@@ -430,8 +430,8 @@ multiple clone approach, and explain in more detail these basic steps.
 
 For more advanced explanations about :ref:`null merges <hg-null-merge>`,
 :ref:`heads merges <hg-heads-merge>`, :ref:`merge conflicts
-<hg-merge-conflicts>`, etc., see the :ref:`FAQs for core developers
-<core-devs-faqs>`.
+<hg-merge-conflicts>`, etc., see the :ref:`version control for core developers
+<version-core-devs>`.
 
 .. _share extension: https://www.mercurial-scm.org/wiki/ShareExtension
 
 
@@ -11,25 +11,32 @@ mailing lists, but also other forms
8000
.
 Mailing Lists
 -------------
 
-The primary mailing list where discussions about Python's development occur is
-python-dev_. The list is open to the public and is subscribed to by all core
+python-dev_ is the primary mailing list for discussions about Python's
+development. The list is open to the public and is subscribed to by all core
 developers plus many people simply interested in following Python's
 development. Discussion is focused on issues related to Python's development,
-such as how to handle a specific issue, a PEP, etc. Ideas about new
-functionality should **not** start here and instead should be sent to
-python-ideas_. Technical support questions should also not be asked here and
-instead should go to python-list_ or python-help_.
+such as how to handle a specific issue, a PEP, etc.::
+
+   - Ideas about new functionality should **not** start here and instead
+     should be sent to python-ideas_.
+   - Technical support questions should also not be asked here and instead
+     should go to python-list_ or python-help_.
+
+Python-ideas_ is a mailing list open to the public to discuss ideas on changing
+Python. If a new idea does not start here (or python-list_, discussed below),
+it will get redirected here.
+
+Sometimes people post new ideas to python-list_ to gather community opinion before
+heading to python-ideas_. The list is also sometimes known as comp.lang.python,
+the name of the newsgroup it mirrors (it is also known by the abbreviation
+c.l.py).
 
 The python-committers_ mailing list is a private mailing list for core
 developers (the archives are publicly available).
 If something only affects core developers (e.g., the
 tree is frozen for commits, etc.), it is discussed here instead of python-dev
 to keep traffic down on the latter.
 
-Python-ideas_ is a mailing list open to the public to discuss ideas on changing
-Python. If a new idea does not start here (or python-list_, discussed below),
-it will get redirected here.
-
 Python-checkins_ sends out an email for every commit to Python's various
 repositories from https://hg.python.org. All core developers
 subscribe to this list and are known to reply to these emails to make comments
@@ -41,10 +48,9 @@ only want an email for when a new issue is open, subscribe to
 new-bugs-announce_. If you would rather receive an email for all changes made
 to any issue, subscribe to python-bugs-list_.
 
-Sometimes people post new ideas to python-list_ to gather community opinion before
-heading to python-ideas_. The list is also sometimes known as comp.lang.python,
-the name of the newsgroup is mirrors (it is also known by the abbreviation
-c.l.py).
+General Python questions should go to `python-list`_ or `tutor`_
+or similar resources, such as StackOverflow_ or the ``#python`` IRC channel
+on Freenode_.
 
 A complete list of Python mailing lists can be found at http://mail.python.org.
 Most lists are also mirrored at http://news.gmane.org/ and can be read and
@@ -60,6 +66,9 @@ RSS feed readers.
 .. _python-help: http://mail.python.org/mailman/listinfo/python-help
 .. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas
 .. _python-list: http://mail.python.org/mailman/listinfo/python-list
+.. _tutor: http://mail.python.org/mailman/listinfo/tutor
+.. _StackOverflow: http://stackoverflow.com/
+.. _Freenode: http://freenode.net/
 
 
 IRC
@@ -79,3 +88,15 @@ Blogs
 Several core developers are active bloggers and discuss Python's development
 that way. You can find their blogs (and various other developers who use Python)
 at http://planet.python.org/.
+
+
+Standards of behaviour in these communication channels
+------------------------------------------------------
+We try to foster environments of mutual respect, tolerance and encouragement,
+as described in the PSF's `Diversity Statement`_. Abiding by the guidelines
+in this document and asking questions or posting suggestions in the
+appropriate channels are an excellent way to get started on the mutual respect
+part, greatly increasing the chances of receiving tolerance and encouragement
+in return.
+
+.. _Diversity Statement: http://www.python.org/psf/diversity/
@@ -64,8 +64,7 @@ You need to provide an SSH-2 key to be able to commit code. You may have
 multiple keys if you wish (e.g., for work and home). Using Ed25519 keys is
 encouraged. Send your key as an attachment in an email to
 hgaccounts@python.org along with your GitHub username so you can be added to
-the "Python core" team at https://github.com/python. Help in generating an SSH
-key can be found in the :ref:`faq`.
+the "Python core" team at https://github.com/python.
 
 Your SSH key will be set to a username in the form of "first_name.last_name".
 This should match your username on the issue tracker.
@@ -165,3 +164,142 @@ break or figure out what you need to do to make it enjoyable again.
 
 
 .. _PSF Code of Conduct: https://www.python.org/psf/codeofconduct/
+
+
+.. _version-core-devs:
+
+Version control for core developers
+-----------------------------------
+
+.. _hg-commit:
+
+How do I commit a change to a file?
+'''''''''''''''''''''''''''''''''''
+
+To commit any changes to a file (which includes adding a new file or deleting
+an existing one), you use the command::
+
+ hg commit [PATH]
+
+``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).  Mercurial will then abort the commit operation so that you can
+try again later.
+
+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 commit 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.
+
+
+.. _hg-merge-conflicts:
+
+How do I solve merge conflicts?
+'''''''''''''''''''''''''''''''
+
+The easiest way is to install KDiff3 --- Mercurial will open it automatically
+in case of conflicts, and you can then use it to solve the conflicts and
+save the resulting file(s).  KDiff3 will also take care of marking the
+conflicts as resolved.
+
+If you don't use a merge tool, you can use ``hg resolve --list`` to list the
+conflicting files, resolve the conflicts manually, and the use
+``hg resolve --mark <file path>`` to mark these conflicts as resolved.
+You can also use ``hg resolve -am`` to mark all the conflicts as resolved.
+
+.. note::
+   Mercurial will use KDiff3 automatically if it's installed and it can find
+   it --- you don't need to change any settings.  KDiff3 is also already
+   included in the installer of TortoiseHg.  For more information, see
+   https://www.mercurial-scm.org/wiki/KDiff3.
+
+
+.. _hg-null-merge:
+
+How do I make a null merge?
+'''''''''''''''''''''''''''
+
+If you committed something (e.g. on 3.5) that shouldn't be ported on newer
+branches (e.g. on default), you have to do a *null merge*::
+
+   cd 3.x
+   hg merge 3.5
+   hg revert -ar default
+   hg resolve -am  # needed only if the merge created conflicts
+   hg ci -m '#12345: null merge with 3.5.'
+
+Before committing, ``hg status`` should list all the merged files as ``M``,
+but ``hg diff`` should produce no output.  This will record the merge without
+actually changing the content of the files.
+
+
+.. _hg-heads-merge:
+
+I got "abort: push creates new remote heads!" while pushing, what do I do?
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+If you see this message while pushing, it means that you committed something
+on a clone that was not up to date, thus creating a new head.
+This usually happens for two reasons:
+
+1. You forgot to run ``hg pull`` and/or ``hg up`` before committing;
+2. Someone else pushed on the main repo just before you, causing a push race;
+
+First of all you should pull the new changesets using ``hg pull``.  Then you can
+use ``hg heads`` to see which branches have multiple heads.
+
+If only one branch has multiple heads, you can do::
+
+   cd default
+   hg heads .
+   hg up csid-of-the-other-head
+   hg merge
+   hg ci -m 'Merge heads.'
+
+``hg heads .``  will show you the two heads of the current branch: the one you
+pulled and the one you created with your commit (you can also specify a branch
+with ``hg heads <branch>``).  While not strictly necessary, it is highly
+recommended to switch to the other head before merging.  This way you will be
+merging only your changeset with the rest, and in case of conflicts it will be
+a lot easier.
+
+If more than one branch has multiple heads, you have to repeat these steps for
+each branch.  Since this creates new changesets, you will also have to
+:ref:`merge them between branches <branch-merge>`.  For example, if both ``3.5``
+and ``default`` have multiple heads, you should first merge heads in ``3.5``,
+then merge heads in ``default``, and finally merge ``3.5`` with ``default``
+using ``hg merge 3.5`` as usual.
+
+In order to avoid this, you should *always remember to pull and update before
+committing*.
+
+
+How do I undo the changes made in a recent commit?
+''''''''''''''''''''''''''''''''''''''''''''''''''
+
+First, this should not happen if you take the habit of :ref:`reviewing changes
+<hg-status>` before committing them.
+
+In any case, run::
+
+ 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.
+
+.. note::
+   These instructions are for Mercurial 1.7 and higher.  ``hg backout`` has
+   a slightly different behaviour in versions before 1.7.