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