annotate doc/README @ 34815:68e0bcb90357

subrepo: share instead of clone if the parent repo is shared (issue5675) (BC)

Previously, only the top level repo was shared, and then any subrepos were
cloned on demand.  This is problematic because commits to the parent repo would
write an updated .hgsubstate to the share source, but the corresponding subrepo
commit would be stuck in the local subrepo.  That would prevent an update in the
source repo.  We already go to great lengths to avoid having inconsistent repos
(e.g., `hg push -r rev` will push _everything_ in a subrepo, even if it isn't
referenced in one of the parent's outgoing commits).  Therefore, this seems like
a bug fix, and there's no option to get the old behavior.  I can't imagine the
previous behavior was useful to anybody.

There shouldn't be an issue with svn, since it is centralized.  Maybe --git-dir
can be used for git subrepos, but I'll leave that to someone more familiar with
git.

An integer was previously being implicitly returned from commands.share(), which
caused dispatch() to start crashing when changing over to returning the shared
repo.  All error paths appear to raise, so this can be hardcoded to success.
The clone command checks for 'is None' in a similar pattern, but since
hg.clone() always returns a tuple, that seems wrong?

.. fix:: Issue 5675

   Creating a share of a repository with a Mercurial subrepository will now
   share the subrepository.

and

.. bc::

   Mercurial subrepositories are now shared instead of cloned when the parent
   repository is shared.  This prevents dangling subrepository references in the
   share source.  Previously shared repositories with cloned subrepositories
   will continue to function unchanged.

Mercurial's documentation is kept in reStructuredText format, which is
a simple plain text format that's easy to read and edit:

  http://docutils.sourceforge.net/rst.html

It's also convertible to a variety of other formats including standard
UNIX man page format and HTML. You'll need to install Docutils:

  http://docutils.sourceforge.net/

Use the Makefile in this directory to generate the man and HTML pages.