Patchwork internals: add some brief documentation about censor

login
register
mail settings
Submitter Augie Fackler
Date Feb. 27, 2017, 11:11 p.m.
Message ID <065219350c9ce3c31a35.1488237075@imladris.local>
Download mbox | patch
Permalink /patch/18816/
State Deferred, archived
Headers show

Comments

Augie Fackler - Feb. 27, 2017, 11:11 p.m.
# HG changeset patch
# User Augie Fackler <augie@google.com>
# Date 1485220644 18000
#      Mon Jan 23 20:17:24 2017 -0500
# Node ID 065219350c9ce3c31a35d13fe97be0673e321e09
# Parent  3f8f53190d6afed0aca6c6527236edad28ce785c
internals: add some brief documentation about censor
Yuya Nishihara - March 10, 2017, 4:11 a.m.
On Mon, 27 Feb 2017 18:11:15 -0500, Augie Fackler wrote:
> # HG changeset patch
> # User Augie Fackler <augie@google.com>
> # Date 1485220644 18000
> #      Mon Jan 23 20:17:24 2017 -0500
> # Node ID 065219350c9ce3c31a35d13fe97be0673e321e09
> # Parent  3f8f53190d6afed0aca6c6527236edad28ce785c
> internals: add some brief documentation about censor

Queued, thanks.

Can you update the help.internalstable?

Patch

diff --git a/mercurial/help/internals/censor.txt b/mercurial/help/internals/censor.txt
new file mode 100644
--- /dev/null
+++ b/mercurial/help/internals/censor.txt
@@ -0,0 +1,22 @@ 
+The censor system allows retroactively removing content from
+files. Actually censoring a node requires using the censor extension,
+but the functionality for handling censored nodes is partially in core.
+
+Censored nodes in a filelog have the flag ``REVIDX_ISCENSORED`` set,
+and the contents of the censored node are replaced with a censor
+tombstone. For historical reasons, the tombstone is packed in the
+filelog metadata field ``censored``. This allows censored nodes to be
+(mostly) safely transmitted through old formats like changegroup
+versions 1 and 2. When using changegroup formats older than 3, the
+receiver is required to re-add the ``REVIDX_ISCENSORED`` flag when
+storing the revision. This depends on the ``censored`` metadata key
+never being used for anything other than censoring revisions, which is
+true as of January 2017. Note that the revlog flag is the
+authoritative marker of a censored node: the tombstone should only be
+consulted when looking for a reason a node was censored or when revlog
+flags are unavailable as mentioned above.
+
+The tombstone data is a free-form string. It's expected that users of
+censor will want to record the reason for censoring a node in the
+tombstone. Censored nodes must be able to fit in the size of the
+content being censored.