* [RFC] A Notedb Standard
@ 2017-03-24 10:37 Richard Ipsum
0 siblings, 0 replies; only message in thread
From: Richard Ipsum @ 2017-03-24 10:37 UTC (permalink / raw)
To: git; +Cc: Dave Borowitz, Stefan Beller, Edwin Kempin
Hello again,
Apologies to those who will receive this for a second time,
git@vger.kernel.org rejected the previous mail.
This follows from previous discussion[1].
I must firstly apologise for taking such a long time to produce a
written spec which I believe I promised over a year ago, but better
late than never... :)
This document is nowhere near complete. My hope is that this initial effort
helps start the conversation.
Thanks,
Richard Ipsum
[1]: https://public-inbox.org/git/20160108140831.GA10200@salo/
Network Working Group R. Ipsum
Internet-Draft Codethink Ltd
Intended status: Informational March 07, 2017
Expires: September 8, 2017
Notedb
draft-ndb-00
Abstract
This document aims to address the absence of a standard for storing
review metadata in git. Notedb is an existing format used in
production. This document aims to encourage more widespread adoption
of Notedb by Code Review and Patch tracking services.
Items or Changes submitted for review can be described in Notedb
using a combination of commit message footers and git notes.
Mutations to changes can be described by adding new commits to an
ordinary git history. Other more qualitative content such as
comments or responses to items submitted for review can be stored in
git as git notes. References to this git history can be stored
within their own git reference hierarchy effectively name-spacing
them from ordinary git branches.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 8, 2017.
Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved.
Ipsum Expires September 8, 2017 [Page 1]
\f
Internet-Draft ndb March 2017
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Semantic description of entities and relations . . . . . . . 5
2.1. Change . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2. ChangeId . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3. ChangeRef . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4. ChangeHistory . . . . . . . . . . . . . . . . . . . . . . 5
2.5. PatchSet . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6. PatchLineComment . . . . . . . . . . . . . . . . . . . . 6
2.7. PatchSetApproval . . . . . . . . . . . . . . . . . . . . 7
2.8. Reviewer . . . . . . . . . . . . . . . . . . . . . . . . 7
2.9. Footer . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.9.1. Branch . . . . . . . . . . . . . . . . . . . . . . . 8
2.9.2. Commit . . . . . . . . . . . . . . . . . . . . . . . 8
2.9.3. Patch-set . . . . . . . . . . . . . . . . . . . . . . 8
2.9.4. Status . . . . . . . . . . . . . . . . . . . . . . . 8
2.9.5. Subject . . . . . . . . . . . . . . . . . . . . . . . 8
3. Syntactic description of entities and relations . . . . . . . 8
3.1. ChangeId . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2. ChangeRef . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3. PatchLineComment . . . . . . . . . . . . . . . . . . . . 9
3.4. PatchSet . . . . . . . . . . . . . . . . . . . . . . . . 12
3.5. PatchSetApproval . . . . . . . . . . . . . . . . . . . . 12
4. Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1. Creating a Change . . . . . . . . . . . . . . . . . . . . 13
4.2. Inserting a new PatchSet . . . . . . . . . . . . . . . . 14
4.3. Inserting a PatchLineComment . . . . . . . . . . . . . . 15
4.4. Inserting a PatchSetApproval . . . . . . . . . . . . . . 16
4.5. Updating the status of a change . . . . . . . . . . . . . 17
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.1. Normative References . . . . . . . . . . . . . . . . . . 17
5.2. Informative References . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18
Ipsum Expires September 8, 2017 [Page 2]
\f
Internet-Draft ndb March 2017
1. Introduction
Reviews occur alongside code, in-between submission of a change and
merge of that change, git tracks the change that was added but does
not track the decisions that led to the change being added.
Presently git lacks any sort of standard for tracking review content,
and so lacks data critical to any kind of code audit.
Gerrit provides one solution to this problem in the form of Notedb.
Notedb is currently an implementation detail of gerrit, this document
seeks to make it the standard for reviews in git.
The notedb format provides a standard allowing all notedb
implementations to reliably obtain and modify review content from git
repositories.
Review content, in this document means, comments on a set of patches,
comments on individual files within a set of patches and comments on
individual lines and ranges of lines with a set of patches. The
state of a review, which describes whether the change is considered
to be new, abandoned or merged.
Notedb is so called because it is loosely based around [git-notes].
If we think of git as a key-value store with shas as keys and values
of either blob, tree or commit, then notes can be thought of as
arbitrary blobs keyed on the sha of the commit they belong to.
When "git notes add" is used to add a note to a commit, git creates a
new tree with an entry that has the sha of the commit the note
belongs to as the entry name (or the key), this key maps to a blob
that contains the contents of this git note. This tree can be found
under the ref refs/notes/commits.
Ipsum Expires September 8, 2017 [Page 3]
\f
Internet-Draft ndb March 2017
% git notes add -m 'This is the contents of a git note!'
% git show
commit 68b41139d0bf2b6b69cdbfb3b5966427d5e6790a
Author: Alice <alice@floof>
Date: Sun Feb 12 23:36:25 2017 +0000
Add cat
Notes:
This is the contents of a git note!
...
% git cat-file -p refs/notes/commits:68b4113...
This is the contents of a git note!
Notedb uses this same principal to store review content within the
git repo itself.
1.1. Requirements Notation
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in BCP 14,
[RFC2119] and indicate requirement levels for compliant Notedb
implementations.
All grammars provided in this document are to be interpreted using
ABNF as described in [RFC5234].
1.2. Terminology
A _Change_ is an individual review submission.
A _ChangeId_ is a unique identifier for a _Change_.
A _PatchLineComment_ is a comment on a _PatchSet_.
A _PatchSet_ is a set of commits submitted as part of a _Change_.
A _PatchSetApproval_ is a special kind of comment on a review that
assigns a numeric value to a Change.
A _Reviewer_ is an external entity that submits a _PatchLineComment_
or a _PatchSetApproval_ to a given _PatchSet_.
A _ChangeHistory_ is the git history of a _Change_.
Ipsum Expires September 8, 2017 [Page 4]
\f
Internet-Draft ndb March 2017
A _ChangeRef_ is a git reference that points to the HEAD commit of a
_ChangeHistory_.
A _Footer_ is a line of form `Key: Value' at the end of a commit
message. A commit message MAY contain multiple Footers.
A _Revision_ is a commit in a git repository that is the HEAD of a
git branch submitted for review.
2. Semantic description of entities and relations
2.1. Change
A _Change_ is an individual review submission. A _Change_ MUST have
one or more _PatchSet_ objects. A _Change_ MUST have an associated
_ChangeRef_. A _Change_ MAY have one or more _Reviewer_ objects.
A _Change_ can be considered a container object for other Notedb
objects such as _PatchSet_ and _Reviewer_ that associates individual
_Reviewer_ and _PatchSet_ objects with a given review submission.
2.2. ChangeId
A _ChangeId_ is a unique identifier for a _Change_. A _Change_ MUST
have a _ChangeId_.
2.3. ChangeRef
A _ChangeRef_ maps a git reference to a _ChangeId_. A _ChangeRef_
MUST point to the HEAD of the _ChangeHistory_ for the given _Change_.
A _ChangeRef_ is used to track the current HEAD of a change history,
git references are used by Notedb to locate changes but they also
ensure that _Change_ metadata is not garbage collected by git.
_ChangeRef_ objects are stored in their own git reference space: they
are effectively namespaced from other git references.
2.4. ChangeHistory
A _ChangeHistory_ is the git history of a _Change_.
The history includes every commit from the initial commit to the HEAD
commit pointed to by the _ChangeRef_.
Notedb stores all operations made against a _Change_ in a git
history, this means that any kind of change made to a Notedb _Change_
is recorded in the git log.
Ipsum Expires September 8, 2017 [Page 5]
\f
Internet-Draft ndb March 2017
A _ChangeHistory_ references the acts of creating/destroying various
git notes that store review metadata such as comments. The commit
messages themselves are also used to record the state of a change at
a given point in the history.
The _Change_ metadata once committed, is immutable, any modifications
to the change are performed by adding a new commit to the
_ChangeHistory_.
The full and current state of a _Change_ is obtained by performing a
walk from the start of the history to the current HEAD commit of the
_ChangeHistory_.
2.5. PatchSet
A _PatchSet_ is an object that MUST point to a _Revision_. A
_PatchSet_ MAY point to one or more _PatchLineComment_ objects. A
_PatchSet_ MAY point to one or more _PatchSetApproval_ objects.
A _PatchSet_ uses a _Revision_ to map content submitted with a
_Change_ to comments and approvals submitted to the a _Change_ by a
_Reviewer_.
When new content is submitted to a _Change_ it is done with a new
_PatchSet_.
It MUST be possible to obtain the state of a _Change_ for every
submission of a new _PatchSet_.
Submitted review content is never deleted or replaced, there is
always a complete audit log of anything that is submitted to a
_Change_.
2.6. PatchLineComment
A _PatchLineComment_ is a comment made by a _Reviewer_ on a specific
section of a file in git. A _PatchLineComment_ MAY contain comments
on one or more separate files stored in git.
A _PatchLineComment_ MUST be associated with the _Reviewer_ that made
the comment. See corresponding syntax section for more details.
A _PatchLineComment_ MUST have content. The content is the body of
the comment itself. See the syntax section, subsection
_PatchLineComment_ for an example of this.
Ipsum Expires September 8, 2017 [Page 6]
\f
Internet-Draft ndb March 2017
2.7. PatchSetApproval
A _PatchSetApproval_ is a special kind of comment on a review that
assigns a numeric value to a _Change_.
A _PatchSetApproval_ will be associated with the _Reviewer_ that made
the approval. See corresponding syntax section for more details.
2.8. Reviewer
A _Reviewer_ is an external entity that MAY submit _PatchLineComment_
or _PatchSetApproval_ objects to a _Change_.
2.9. Footer
A _Footer_ is a key-value pair that is stored at the end of a commit
message. A _Footer_ is commonly used for signing off commits, where
a `Signed-off-by' footer gets appended to the commit message.
Notedb uses commit _Footer_ objects to store some metadata such as
the branch a _Change_ is based on, the status of the _Change_ and the
HEAD commit of the change under review.
A commit footer MUST match the following grammar,
FOOTER = 1*WORD ":" SP 1*WORD
WORD = any CHR but not (SP or TAB or CR or LF)
CHR = any valid character in the commit message encoding
The following footers are currently used:
BRANCH_FOOTER = "Branch" ":" SP 1*WORD
COMMIT_FOOTER = "Commit" ":" SP 1*WORD
PS_FOOTER = "Patch-set" ":" SP 1*WORD
STATUS_FOOTER = "Status" ":" SP 1*WORD
SUBJECT_FOOTER = "Subject" ":" SP 1*WORD
LABEL_FOOTER = "Label" ":" SP 1*WORD
An example _Footer_ in a commit message,
Ipsum Expires September 8, 2017 [Page 7]
\f
Internet-Draft ndb March 2017
commit 3075b9295ec1d909bfce286bb08c0094b3b51700
Author: Alice <alice@floof>
Date: Sun Feb 12 23:36:25 2017 +0000
Add cat
Signed-off-by: Alice <alice@floof>
_Footer_ objects in Notedb are used to specify several metadata
items, these include "Branch", "Commit", "PatchSet", "Status" and
"Subject", the meaning of each of these is defined by the following
subsections.
2.9.1. Branch
This is the name of the git branch the _Change_ should be merged to,
for example, "master". Note that this SHOULD NOT include the "refs/
heads", prefix.
2.9.2. Commit
This is a 40 digit sha1 signature of the HEAD commit of the git
branch that is being submitted for review.
2.9.3. Patch-set
This is the Patchset Id.
2.9.4. Status
This is the "Status" of a _Change_. A _Change_ can be considered to
be "New", "Merged" or "Abandoned".
2.9.5. Subject
This is the "Subject" of a _Change_. It is used for email.
3. Syntactic description of entities and relations
3.1. ChangeId
There are two types of _ChangeId_, one _ChangeId_ is an Integer
value, and is described by the following grammar.
INTCHANGEID = 1*DIGIT
To support the use of Notedb in distributed systems it is useful to
have a more flexible _ChangeId_. The second type of _ChangeId_ is a
Ipsum Expires September 8, 2017 [Page 8]
\f
Internet-Draft ndb March 2017
String value, since the _ChangeId_ is stored in the _ChangeRef_,
there are some further restrictions on what characters may be used in
a String _ChangeId_, the following grammar is provided,
STRCHANGEID = (1*GITREFCHAR) but not BADSTRING
and does not end with ".lock"
and does not end with "/"
GITREFCHAR = not BADCHARACTER
BADCHARACTER = '.' / ':' / '?' / '[' / '\'
/ '^' / '~' / '*' / SP / TAB / CL / LF
BADSTRING = "@{" / ".."
3.2. ChangeRef
The exact form of a _ChangeRef_ MUST match the following grammar:
CHANGEREF = ("refs/" 1*GITREFCHAR "/" GITREFCHAR GITREFCHAR
"/" 2*GITREFCHAR "/meta")
and does not end with ".lock"
and does not end with "/"
GITREFCHAR = not (BADCHARACTER or BADSTRING)
BADCHARACTER = '.' / ':' / '?' / '[' / '\'
/ '^' / '~' / '*' / SP / TAB / CL / LF
BADSTRING = "@{" / ".."
An example _ChangeRef_,
refs/changes/heads/01/1/meta
Another example _ChangeRef_,
refs/foobar/heads/ca/cat/meta
3.3. PatchLineComment
Data for a _PatchLineComment_ is stored in a git note.
The contents of a _PatchLineComment_ is stored in a git note on the
commit the comment applies to. See [git-notes] for details.
The order of individual comments within the git note is
implementation defined, however parsers/emitters of the format MUST
Ipsum Expires September 8, 2017 [Page 9]
\f
Internet-Draft ndb March 2017
preserve the existing order of any existing comments within the
notes: the diff between a _PatchLineComment_ before addition of a new
comment and after addition of a comment SHALL be minimal.
A _PatchLineComment_ MUST contain the following headers,
o Patchset - the patchset id
o Revision - the commit sha this comment refers to
o File - the file this comment refers
o Comment range - the range of lines this comment refers to
o DateTime - the date and time this comment was made
o Author - the author of the comment
o UUID - a unique identifier for the comment
o Bytes - the size of the content in bytes
these headers correspond and MUST match the following grammars,
PATCHSET_ID = 1*DIGIT
REVISION = 40*HEXDIGIT
FILE = 1*ANY
RANGE = (["-"] DIGIT) / ((DIGIT[":" DIGIT])-(DIGIT[":" DIGIT]))
DATETIME = TO BE DISCUSSED
AUTHOR = 1*ANY LEFT_ANGLE AUTHOR_EMAIL RIGHT_ANGLE
AUTHOR_EMAIL = 1*ANY
LEFT_ANGLE = "<"
RIGHT_ANGLE = ">"
UUID = 40*HEXDIGIT
BYTES = 1*DIGIT
where DIGIT, HEXDIGIT, ANY shall be defined as,
DIGIT = '0' / '1' / '2' / '3' / '4' / '5' / '6' / '7' / '8' / '9'
HEXDIGIT = DIGIT / 'a' / 'b' / 'c' / 'd' / 'e' / 'f'
ANY = any valid character or codepoint in the given encoding
Ipsum Expires September 8, 2017 [Page 10]
\f
Internet-Draft ndb March 2017
The remainder of the blob for a single comment consists of the
comment content itself. The number of content bytes MUST be exactly
that specified in the _Bytes_ header.
An example _PatchLineComment_.
Patch-set: 2
Revision: ff66dd146cacf964671f5373f6e20d7e1b80b70c
File: simpcat.1
-1
Wed Feb 15 15:50:32 2017 +0000
Author: Alice <alice@floof>
UUID: 94e69344801b98e2aa07caf2558b587186ddf7af
Bytes: 58
This man page looks okay but I don't know troff that well.
A _PatchLineComment_ MAY contain multiple comments if there are
multiple comments on a given commit. Comments MAY be made on
separate files within a single _PatchLineComment_.
An example _PatchLineComment_ with multiple comments on different
files.
Patch-set: 2
Revision: ff66dd146cacf964671f5373f6e20d7e1b80b70c
File: Makefile
-1
Wed Feb 15 16:08:15 2017 +0000
Author: Alice <alice@floof>
Parent: 94e69344801b98e2aa07caf2558b587186ddf7af
UUID: c26198375e761bbdc30b45951435a30efcd23f7c
Bytes: 122
The makefile looks okay to me.
Though, do you think it'd be useful to let people install cat without
all the other tools?
File: simpcat.1
-1
Wed Feb 15 15:50:32 2017 +0000
Author: Alice <alice@floof>
UUID: 94e69344801b98e2aa07caf2558b587186ddf7af
Bytes: 58
This man page looks okay but I don't know troff that well.
Ipsum Expires September 8, 2017 [Page 11]
\f
Internet-Draft ndb March 2017
3.4. PatchSet
A _PatchSet_ object has two footers, the first is the "Patch-set"
footer, which stores the id of that _PatchSet_. The second is the
"Commit" footer, which stores the _Revision_ for the _PatchSet_.
A _PatchSet_ MUST have a "Patch-set" footer and MUST have a "Commit"
footer.
o PatchLineComment - any given Patch-set can have multiple
PatchLineComments
o Commit - a commit sha, to map a PatchSet to a commit in the
repository
Below is an example history that includes an initial submission of a
_Change_, with the first _PatchSet_ object being automatically
created, followed by a subsequent update to the _Change_ which
submits a second _PatchSet_.
commit 0226cb1a85573f1db30c553bcd4397ebd6b05fbd
Author: Alice <alice@floof>
Date: Wed Feb 15 15:39:57 2017 +0000
This is my second version of the cat program!
Commit: ff66dd146cacf964671f5373f6e20d7e1b80b70c
Patch-set: 2
commit d096d963d491977b497fed4f194adcf315901d39
Author: Alice <alice@floof>
Date: Wed Feb 15 14:20:13 2017 +0000
This is my cat do you like it?
Branch: master
Commit: 68b41139d0bf2b6b69cdbfb3b5966427d5e6790a
Patch-set: 1
Status: new
Subject: cat
3.5. PatchSetApproval
A _PatchSetApproval_ represents a vote on a given _Change_. It is
stored within a "Label" footer under the "CodeReview" key.
The value for this key shall be a single + or - sign followed by any
number of digits, the following grammar applies:
Ipsum Expires September 8, 2017 [Page 12]
\f
Internet-Draft ndb March 2017
APPROVAL = ["-"] LABEL_FOOTER "CodeReview" ("+" / "-") 1*DIGIT
An example PatchSetApproval,
commit 502c5160b89432b0391a184da2727ff1e23eb875
Author: Alice <alice@floof>
Date: Wed Feb 15 14:32:21 2017 +0000
Vote on patch set 1
Label: CodeReview=+1
Patch-set: 1
The details of the exact voting system are left for the consumer of
the library to define.
Once given, a _PatchSetApproval_ can also be removed, this is
indicated by prefixing the review to be removed with a '-' sign, as
shown below.
-Label: CodeReview=+1
4. Appendix
4.1. Creating a Change
Creation of a _Change_ requires:
o A metadata repository
o A content repository
o Change subject
o Commit subject
o Destination branch (the branch the _Change_ should be merged to)
o Author
o Revision id (sha of the HEAD of the branch that we wish to merge)
o Patchset id
o Ref prefix
Ipsum Expires September 8, 2017 [Page 13]
\f
Internet-Draft ndb March 2017
o Change Id
a _Change_ may optionally specify:
o A topic
topics may be used to group related _Change_ objects together.
Once a _Change_ has been created there shall exist a git reference
and a single commit. The reference is a _ChangeRef_ (as defined by
this document) and points to the commit which contains the initial
_Change_ metadata in its commit message.
So in the example used in this document, the git reference is
"refs/changes/ca/cat/meta" and the commit is as shown below:
commit d096d963d491977b497fed4f194adcf315901d39
Author: Alice <alice@floof>
Date: Wed Feb 15 14:20:13 2017 +0000
This is my cat do you like it?
Branch: master
Commit: 68b41139d0bf2b6b69cdbfb3b5966427d5e6790a
Patch-set: 1
Status: new
Subject: cat
4.2. Inserting a new PatchSet
As stated earlier in this document, the revision a _Change_ points to
is immutable, it can only be updated by submitting new _PatchSet_
objects, the _Change_ tracks all _PatchSet_ objects submitted to it,
meaning that all submissions to a _Change_ are tracked and
permanently available.
A new _PatchSet_ is inserted by creating a new commit that contains
the new patchset id (which is the previous patchset id incremented)
and a new revision id (this must not be the same id as the previous
_PatchSet_). The "Patch-set" footer stores the patchset id. The
"Commit" footer stores the revision id. The history below shows the
_Change_ after a new _PatchSet_ has been inserted.
Ipsum Expires September 8, 2017 [Page 14]
\f
Internet-Draft ndb March 2017
commit 0226cb1a85573f1db30c553bcd4397ebd6b05fbd
Author: Alice <alice@floof>
Date: Wed Feb 15 15:39:57 2017 +0000
This is my second version of the cat program!
Commit: ff66dd146cacf964671f5373f6e20d7e1b80b70c
Patch-set: 2
commit d096d963d491977b497fed4f194adcf315901d39
Author: Alice <alice@floof>
Date: Wed Feb 15 14:20:13 2017 +0000
This is my cat do you like it?
Branch: master
Commit: 68b41139d0bf2b6b69cdbfb3b5966427d5e6790a
Patch-set: 1
Status: new
Subject: cat
Once the new commit is added, the _ChangeRef_ is subsequently updated
to point to it. That is "refs/changes/heads/ca/cat/meta" now points
to "0226cb1".
4.3. Inserting a PatchLineComment
During review people will generally comment on specific sections of a
patch. The _PatchLineComment_ facilitates such aspects of a review,
a _PatchSet_ object can be effectively annotated with
_PatchLineComment_ objects.
To create a _PatchLineComment_, first a blob is created containing
the appropriate headers, for example.
Ipsum Expires September 8, 2017 [Page 15]
\f
Internet-Draft ndb March 2017
Patch-set: 2
Revision: ff66dd146cacf964671f5373f6e20d7e1b80b70c
File: Makefile
-1
Wed Feb 15 16:08:15 2017 +0000
Author: Alice <alice@floof>
Parent: 94e69344801b98e2aa07caf2558b587186ddf7af
UUID: c26198375e761bbdc30b45951435a30efcd23f7c
Bytes: 122
The makefile looks okay to me.
Though, do you think it'd be useful to let people install cat without
all the other tools?
The blob is added to a tree, the entry name of the tree being the sha
of the _Revision_, in this case "ff66dd1", so that we have a tree as
shown below:
100644 blob 35e25b2... ff66dd1...
finally a commit is then created that points to this tree.
commit a2ed0172a15f489f9ef10c78d2b734a21287c21e
Author: Alice <alice@floof>
Date: Wed Feb 15 15:50:32 2017 +0000
Metadata update
Patch-set: 2
the _ChangeRef_ is then updated to point to this commit, so
"refs/changes/heads/ca/cat/meta" now points to "a2ed017".
4.4. Inserting a PatchSetApproval
During review people will also generally vote on whether a given
_Change_ should be merged or not, typically a vote is an annotation
of +1 meaning "yes this should be merged", or -1 meaning "no this
should not be merged", some systems also support the idea of +2 or -2
which are stronger versions of +1 or -1. As stated earlier in this
document the Notedb format leaves the exact rules of the voting
system for the consumer of the format to define, though within
certain constraints, see the earlier definition of _PatchSetApproval_
for details.
Ipsum Expires September 8, 2017 [Page 16]
\f
Internet-Draft ndb March 2017
Essentially a _PatchSetApproval_ has a 'magnitude' in the form of an
integer. And a 'sign', positive or negative. So to represent a +1
the following commit is added,
commit 502c5160b89432b0391a184da2727ff1e23eb875
Author: Alice <alice@floof>
Date: Wed Feb 15 14:32:21 2017 +0000
Vote on patch set 1
Label: CodeReview=+1
Patch-set: 1
the _ChangeRef_ is then updated to point to this commit, so
"refs/changes/heads/ca/cat/meta" now points to "502c516".
4.5. Updating the status of a change
Eventually, once reviews are completed there will be a need to update
the status of a _Change_. In Notedb changes are either "New",
"Abandoned", or "Merged". When a change is merged or abandoned the
only update to the metadata is to the _ChangeStatus_, as shown below,
commit d36c719027573435d6f07ce53fe9cfd4b8095612
Author: Alice <alice@floof>
Date: Mon Mar 20 17:33:23 2017 +0000
Metadata update
Patch-set: 4
Status: abandoned
please note no metadata is destroyed or removed. This is a very
important point, all history of all submitted changes is kept in the
repository for posterity.
5. References
5.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
Ipsum Expires September 8, 2017 [Page 17]
\f
Internet-Draft ndb March 2017
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/
RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>.
5.2. Informative References
[git-notes]
Git Community, ., "git-notes documentation", n.d.,
<https://git-scm.com/docs/git-notes>.
Author's Address
Richard Ipsum
Codethink Ltd
Ducie House 37 Ducie Street
Manchester M1 2JW
United Kingdon
Phone: +44 161 236 5575
Email: richard.ipsum@codethink.co.uk
Ipsum Expires September 8, 2017 [Page 18]
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2017-03-24 10:37 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-03-24 10:37 [RFC] A Notedb Standard Richard Ipsum
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).