create mercurial section in devguide's committing.rst

[cjerdonek]

BPO	17284
Nosy	@terryjreedy, @ncoghlan, @pitrou, @ezio-melotti, @merwok, @sandrotosi, @cjerdonek, @willingc
Files	mercurial-section-1.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2015-04-14.15:16:51.096>
created_at = <Date 2013-02-24.08:37:39.081>
labels = ['easy', 'type-feature', 'invalid', 'docs']
title = "create mercurial section in devguide's committing.rst"
updated_at = <Date 2015-04-14.15:16:51.094>
user = 'https://github.com/cjerdonek'

bugs.python.org fields:

activity = <Date 2015-04-14.15:16:51.094>
actor = 'willingc'
assignee = 'none'
closed = True
closed_date = <Date 2015-04-14.15:16:51.096>
closer = 'willingc'
components = ['Devguide']
creation = <Date 2013-02-24.08:37:39.081>
creator = 'chris.jerdonek'
dependencies = []
files = ['29217']
hgrepos = []
issue_num = 17284
keywords = ['patch', 'easy']
message_count = 7.0
messages = ['182859', '183016', '183125', '183128', '183131', '183133', '240904']
nosy_count = 9.0
nosy_names = ['terry.reedy', 'ncoghlan', 'pitrou', 'ezio.melotti', 'eric.araujo', 'sandro.tosi', 'chris.jerdonek', 'tshepang', 'willingc']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue17284'
versions = []

[cjerdonek]

As discussed in bpo-14468, this issue is to reorder the sections in the devguide's committing.rst to create a section dedicated to using Mercurial when committing. The attached patch is adapted from the "2-move_two_sections.diff" patch of that issue.

[ezio-melotti]

This has now been committed as part of bpo-14468.
Regarding the change of the section title, I'm not sure that's necessary.
Currently the section covers all the fundamental Mercurial-related operations that a committers needs to know (set up, commit, merge, push), not just committing.
I suggest closing this as out of date.

[cjerdonek]

Currently the section covers all the fundamental Mercurial-related operations that a committers needs to know (set up, commit, merge, push), not just committing.

The point of the change in section title is to have a title so non-committers know they can skip over the section. I'm not wedded to the title I initially suggested. "Mercurial Guide for Committers" is another possibility. Mercurial information common to both committers and non-committers can go in a more generally titled section like "Working with Mercurial."

[ezio-melotti]

The point of the change in section title is to have a title so
non-committers know they can skip over the section.

In the first part of committing.rst there are also things for committers only, and some of the content of the "working with mercurial" might be interesting for non committers too.

We could add a note at the beginning of the page that says that this page is mainly intended for committers, and that contributors can skip it or just skim through it.

I also wonder if we should make the distinction between committers and contributors docs more evident, but in any case there's going to be
some overlapping.

[cjerdonek]

I think making the sections more focused helps because sections are the linkable units, and sections can be freely moved around once they are more stand-alone (e.g. into or out of the FAQ).

In bpo-16931 in response to Ned, I suggested adding a general Mercurial section before the Mercurial section specific to committers. I can propose a patch.

[ezio-melotti]

The problem with that is that you have to navigate through different links/pages/sections though (see also msg182645).

[willingc]

I've reviewed this issue at the PyCon sprint. While I agree that there are sections that new contributors might wish to skip over, I believe that there is content that would benefit contributors that are not yet core developers.

Going forward we can try to keep general contributor information to the top of a sub-section with more advanced or core developer specific information toward the bottom of a sub-section. This will enable contributors to grow their skills over time as their experience grows.

Thanks Chris and Ezio. I am closing this issue but please file new issues if specific wording in a subsection could be more developer friendly.