Open Bug 1187751 Opened 6 years ago Updated 6 years ago

Need a documentation about basic mercurial workflow, especially creating a patch, for newcomer.

Categories

(Developer Services :: General, task)

task
Not set
normal

Tracking

(Not tracked)

ASSIGNED

People

(Reporter: arai, Assigned: gps)

References

Details

Mercurial pages on MDN [1] are now marked as obsolete, and redirected to "Mercurial for Mozillians" page on Read the Docs [2].  But latter one doesn't explain much about "how to make a patch file", e.g. `hg export` (or `hg bzexport`?) [3].  And before that section, it explains "SSH Configuration" [4] for MozReview.  These are confusing and not helpful for newcomer who doesn't have commit access.

So, we need a documentation page which explains basic workflow for newcomer, as a complementary for "How to Submit a Patch" page [5], which has a link [6] to "Using Mercurial" page now [1].

Then, I have some questions:
  1. What's the current recommended workflow for newcomer?
    1-a. Is "How to Submit a Patch" page still describing recommended workflow?
    1-b. Is bookmark recommended than mq for newcomer?
    1-c. Is `hg bzexport` recommended than `hg export`?
         to be honest, this kind of automation command should be scary for newcomer,
         because they don't know what is automated and what happens after they hit enter.
         so, if we recommend bzexport, detailed explanation should be needed.
  2. Where to add these documentation?  MDN or Read the Docs?
     If to MDN, can we create a new page and move some section from "Using Mercurial" page [1]? or move existing pages back to original place and remove obsoleted(?) sections?

[1] https://developer.mozilla.org/en-US/docs/Archive/Mozilla/Mercurial/Using_Mercurial#How_can_I_generate_a_patch_for_somebody_else_to_check-in_for_me.3F
[2] http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html
[3] http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/bookmarks.html#exporting-patch-files
[4] http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/auth.html
[5] https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/How_to_Submit_a_Patch
[6] https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/How_to_Submit_a_Patch#Creating_a_patch
Not sure if I suggested the right component; please let me know if there's a better one.
Flags: needinfo?(gps)
A few people have asked for a concise article on recommended workflows. I'll try to piece one together.
Assignee: nobody → gps
Status: NEW → ASSIGNED
Once something is created here, I'll update the a-team's bootcamp docs (https://ateam-bootcamp.readthedocs.org/en/latest/guide/development_process.html#mercurial) to point at it :-)
url:        https://hg.mozilla.org/hgcustom/version-control-tools/rev/43d47377b008c770109aeda87797dee48848da28
changeset:  43d47377b008c770109aeda87797dee48848da28
user:       Gregory Szorc <gps@mozilla.com>
date:       Tue Aug 18 09:38:53 2015 -0700
description:
docs: major updates to Mercurial docs (bug 1187751)

Added an article on how the DAG works.

Added article on workflows.

Added article on Firefox-specific workflow.
Even with my major docs update, there is still a bunch of info from comment #0 that needs included and/or updated.

I have a Q3 deliverable to enable anyone to push changes to MozReview. (You currently need a Mozilla LDAP account.) Once this is in place, MozReview will replace bzexport/Bugzilla attachments as the mechanism contributors use to submit changes to Mozilla. At that time, a lot of docs become clearly outdated.

I'll leave this bug open to track updating things once anonymous pushes are implemented.
Flags: needinfo?(gps)
Depends on: 1195856
You need to log in before you can comment on or make changes to this bug.