# Draft Proposal for git notes usage Often times we need to do things to a commit after the fact. relnotes: yes was the first thing we discovered, and worked around that problem with a RELNOTES file. 'MFC After' also suffers from this problem. This proposal assumes that we're enforcing the git trailer rule. Namely that all our metadata is dash separated, not space separated. This proposal lays out a standard that our tooling will use and enforce. Notes will be added to commits in the source of truth FreeBSD repo. These notes are not pushed to github, so people wishing to use this tooling will need to add pulling of notes with ` fetch = +refs/notes/*:refs/notes/*` in their .git/config. ## Start managing notes on commits The basic proposal is to move some of the metadata that we current put in-line in the commit to notes (though there's not a lot of harm allowing some of this inline, some things are impossible like `MFC-With`). ### Relnotes: {yes,no} Adding this to notes will let people retroactively tag relnotes items. Often times, we need to do this because the original committer didn't know, at the time of the commit, the commit was of interest. This won't replace RELNOTES, since that's the place to go for adding extra, free-form context. This should appear only once. ### MFC-After: {time-expr} The MFC tool should be updated to look at Notes for this field. Otherwise, it matches historic behavior. `MFC-After: never` will be used to override a `MFC After` or `MFC-After` in the commit message. But that's just a special case: when MFC-After is in both places, the Notes one wins. There should be only one of these in the notes. ### MFC-Hash: branch hash When a commit is merged, our tooling will add this metadata to the notes. **branch** is the branch it is merged to, and will start with either `releng/` or `stable/`. **hash** is the the hash on that branch. This item can appear multiple times. ### Differential-Revision: url This matches the current practice. This item may appear multiple times. It is sometimes forgotten when the original commit happens. In addition, this will be used by `git arc` to track revisions in Phabricator, though it will fall back to the old methods when this isn't present. ### MFC-With: hash This specifies the **hash** to MFC this commit with. This can be used to augment 'Fixes:' headers. This generally cannot be easily added to commit before hand since you don't know the base hash until it's pushed. So you'd have to push it, then udpate everything else on a branch and push that. `git arc rebase` will likely be needed (or similar name) so that the `MFC-With:` fields can be added reliably by `git arc stage` and reworked when git push races are lost. This may appear more than once. ### Fixes: hash Same as the more-standard git header fixes. This allows us to annotate after the fact when bugs are fixed in non-obvious ways. This may appear multiple times. ## Issues ### git rebase hasn't always been happy with notes A long time ago, git rebase would eat notes. This seems to have been fixed, but testing here has been light. ### Notes versioned? Is there a way to restore accidentally deleted notes. > git log -p notes/commits will list them in the current branch. ``` commit 06d9d2484b51ec6989651960b5f02c4e8a582015 Author: Warner Losh <imp@FreeBSD.org> Date: Mon Feb 12 12:30:42 2024 -0700 Notes removed by 'git notes remove' diff --git a/67/90/74613f7fc5d859005d9a03e33602e5f37e55 b/67/90/74613f7fc5d859005d9a03e33602e5f37e55 deleted file mode 100644 index 2447825f91bd..000000000000 --- a/67/90/74613f7fc5d859005d9a03e33602e5f37e55 +++ /dev/null @@ -1 +0,0 @@ -Differential-Revision: D12335 commit bcbe51ffc554dcaeadb7431acf2eafd7d60d71fe Author: Warner Losh <imp@FreeBSD.org> Date: Mon Feb 12 12:28:41 2024 -0700 Notes added by 'git notes append' diff --git a/67/90/74613f7fc5d859005d9a03e33602e5f37e55 b/67/90/74613f7fc5d859005d9a03e33602e5f37e55 new file mode 100644 index 000000000000..2447825f91bd --- /dev/null +++ b/67/90/74613f7fc5d859005d9a03e33602e5f37e55 @@ -0,0 +1 @@ +Differential-Revision: D12335 ``` after > % git notes append -m'Differential-Revision: D12335' --no-separator HEAD > % git notes remove HEAD ### Notes push hooks Do we have hooks that we can use to be used to limit the blast radius of any oops / bugs / etc.