annotate doc/README @ 26520:46dec89fe888

bookmarks: use recordchange instead of writing if transaction is active

Before this patch, 'bmstore.write()' always write in-memory bookmark
changes into '.hg/bookmarks' regardless of transaction activity.

If 'bmstore.write()' is invoked inside a transaction and it writes
changes into '.hg/bookmarks', then:

  - original bookmarks aren't restored at failure of that transaction

    This breaks "all or nothing" policy of the transaction.

    BTW, "hg rollback" can restore bookmarks successfully even before
    this patch, because original bookmarks are saved into
    '.hg/journal.bookmarks' at the beginning of the transaction, and
    it (actually renamed as '.hg/undo.bookmarks') is used by "hg
    rollback".

  - uncommitted bookmark changes are visible to other processes

    This is a kind of "dirty read"

For example, 'rebase.rebase()' implies 'bmstore.write()', and it may
be executed inside the transaction of "hg unshelve". Then, intentional
aborting at the end of "hg unshelve" transaction doesn't restore
original bookmarks (this is obviously a bug).

This patch uses 'bmstore.recordchange()' instead of actual writing by
'bmstore._writerepo()', if any transaction is active

This patch also removes meaningless restoring bmstore explicitly at
the end of "hg shelve".

This patch doesn't choose fixing each 'bmstore.write()' callers as
like below, because writing similar code here and there is very
redundant.

  before:
    bmstore.write()

  after:
    tr = repo.currenttransaction()
    if tr:
        bmstore.recordchange(tr)
    else:
        bmstore.write()

Even though 'bmstore.write()' itself may have to be discarded by
putting bookmark operations into transaction scope, this patch chose
fixing it to implement "transactional dirstate" at first.

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.