openSUSE:ALP/Workgroups/Git-Packaging-Workflow/WorkPackages/changesfile

Jump to: navigation, search

Rework changes file handling with Git-Packaging-Workflow

We can take a look at how we can replace the currently mandatory $pkgname.changes file with some git intrinsic methods

Requirements for a .changes file replacement

  • It must be possible to modify historic change file entries (e.g. after the change got already accepted into openSUSE Factory) on an exceptional basis to add, modify or remove bugzilla, CVE or jira references without rewriting git history.
  • It should be convenient to submit internal commit messages and user/customer visible summary changes for a packager. Also the review of those needs to be easily possible (as part of the regular pull request review workflow, for example)
  • the user visible changes should be following git merges/cherry-picks automatically, ideally without any manual work, resolving of merge conflicts and the like

Options

Dan's git tag based proposal

  • Use tags to mark the commits that will be used to generate the changelog entries
  • Commits without a tag would be ignored in the changelog, the ones with tags will be described
  • Likely has problems with cherry-pick
    • Those tags can be pushed, edited, deleted and created using git commands. The UX is not ideal but the feature is there
    • One missing point can be that cannot be part of a PR (PR can not consist of tags)
  • Alternative: invent a commit message syntax that obsoletes (replaces) a previous commit message identified by a gitshasum
  • Major downsides:
    • PR UX is not there
    • additional tooling for cherry-picking & merging necessary


Using git notes for tracking the user-visible changelog

AI Manuel/Alberto

  • Git notes[1] is a feature present in git since 1.7 (2011).
  • It is used to attach information (extensions to the commit message, usually) into other git objects (normally commits)
  • The notes are stored as a series of linear (they can be merged tho) commits, references by default from refs/notes/commits
  • Those commits can be inspected by the usual tools, like gitk --all or git log -p notes/commits
  • Each note is a file object, with the name of the commit that is associated and the content is the note message
  • Creating a note associated to a commit is done via git note {add|append} <hash>. If <hash> is omitted HEAD will be used.
  • Editing a note (git note {edit|append}) or removing a note (git note remove) will create a new note commit with the new message (in the case of removal will be an empty object)
  • Notes can be exported with git format-patch --notes HEAD~1
  • Can be pushed (git push origin refs/notes/*) and fetched (git fetch origin refs/notes/*:refs/notes/*), so can be stored in a remote repo and shared from there
  • To simplify the command git can be configured with (git config --add remote.origin.push '+refs/notes/*:refs/notes/*'; git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*')
  • Notes can be inspected directly with the log: git log. It will show the note under the commit message, prefixed with a header
  • Notes can be namespaced. We can use multiple references to store the different note branches. git note --ref=maintenance add will create the reference "refs/notes/maintenance", and a set of commits separated in a different branch.
  • With git log --notes=maintenance we can see the notes from different namespaces
  • As any other reference, it can be removed from the remote with git push origin :refs/notes/maintenance
  • gitea shows the commit notes[2] and are visible during a pull request[3]
  • Cherry pick requires to copy the notes: git cherry-pick -x 215c2bb && git notes copy 215c2bb
  • By default rebase should also requires the copy, as the commit hash has changed. But it can be configured to automatically stick the notes of the old commit (notes.rewrite, amend = true, rebase = true)
  • The objects with notes can be listed with git notes list

With this general context, seems now possible to have the changes generated from the commit messages directly, with amends delegated into the notes.

One possible way is to extract the changes from the git history using a tool[4] that is driven by this rules:

  • By default no commit message is extracted into the changelog
  • If the commit message has r"^Changelog:yes$", this commit message will be included in the changelog, with the time and author information from the commit itself.
  • If by mistake a change entry needs to be included, and is too late to edit the commit message (released binary), the user can add a note associated to the amended commit, with r"^Changelog:yes$"
  • If by mistake a change entry needs to be removed, and is too late to edit the commit message, a note can be associated with r"^Changelog:no$"
  • In the same way, if the commit message needs to be included and is marked also as included, but need to be fixed (add a new boo/bsc/CVE reference), a new associated note will be created with the new commit message

Proposal dirk/Using a plain NEWS file for changelog

Currently .changes files handling is a bit cumbersome because (mostly out of historic context) *only* submitrequests with a .changes file addition are being accepted. For the git based workflow, we lift that requirement and

  • require user visible references (bsc, jira, CVE identifiers) as well as version updates to a NEWS file (or _changes or .changes for $pkgname.changes like today) in the same git commit that introduces the change. Advantage: easy to review. Disadvantage: cherry-pick could cause merge conflicts if the context of the NEWS file changed.
  • reviews require a git commit message that could be a copy of the NEWS file entry or empty (doesn't matter).


References

[1] https://git-scm.com/docs/git-notes

[2] https://gitea.opensuse.org/aplanas/notest/commit/215c2bb94e5461cffd61e303001d76148fe470c7

[3] https://gitea.opensuse.org/aplanas/notest/pulls/1/commits

[4] https://gist.github.com/aplanas/917bb47a7631ff657faeff874630642e

Retrieved from "https://en.opensuse.org/index.php?title=openSUSE:ALP/Workgroups/Git-Packaging-Workflow/WorkPackages/changesfile&oldid=169588"