Work On Revising The Definitive Guide

An effort to refresh the Mercurial book, started in May 2011.

Introduction

This is a page to contain information about the ongoing community effort to revise Bryan O'Sullivan's Mercurial: The Definitive Guide.

The current phase of the project is to collect proposed changes to the book -- e.g, areas that must be revised because they are no longer relevant, subjects that should be covered but are missing, etc. One of the important goals is to make sure the book stays relevant to newcomers, so it might be a good idea to separate out "advanced topics" somehow. But an area for "Why is it important?" is included in the lists below so we can have a basis for starting a discussion if someone is concerned about a topic being too advanced or not a good fit for the book.

If you have a suggestion for an area to be improved or revised, or have the necessary expertise and would like to volunteer to write on a suggested topic, please enter the appropriate information in the list below. If you already see an author who has volunteered but would still like to volunteer, then please enter your name. If you want to write about a certain aspect of the topic, then also document that so others can see where their expertise can fill a missing gap. We want to encourage collaboration on the project.

Proposed Topics

Summary command

• This needs to be used early and repeatedly

Named branches

• Emphasize the model described in StandardBranching

• Volunteer authors

  • Steve Losh (irc: sjl)

Subrepos

• When to use them and when not to use them

• Emphasize the model described here by mpm

Bookmarks

• Augie willing to cover this but may not have time, and has some bookmarks workflow thoughts for whomever does.

Revsets

• Volunteer authors

  • Augie Fackler (durin42) - will cover both asking interesting questions with revsets, having set aliases, and (maybe?) adding them in extensions

Rebasing

• Volunteer authors

  • Na'Tosha Bard (irc: natosha) (especially on end-user perspective --rebasing as part of a workflow, what the end user sees when he rebases, caveats, etc, -- not specifically the low-level technical details of how it works)

Deprecated features

• don't mention fetch, hgk, etc.
• de-emphasize repository-based branching
• de-emphasize coding hooks via the API

Repository

The repository being used for this work is located at https://bitbucket.org/natosha_bard/hgbook

Anyone wishing to contribute should fork this repository and submit changes back as a pull request.

CategoryDeveloper