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

Subrepos

• When to use them and when not to use them

• Emphasize the model described here by mpm

Bookmarks

Revsets

Rebasing

• What to cover: What it is, how it works, and when you can (and can't!) do it

• Why is it important? It is a very relevant part of many teams' workflow -- especially as Mercurial gains users who are already familiar with git. But there are caveats to rebasing (especially in a large team with lots of branches) that should be documented and, as far as I can tell, the subject is not covered in the book.

• 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

CategoryDeveloper