On Thu, 27 Feb 2020 at 16:13, Zbigniew Jędrzejewski-Szmek
<zbyszek(a)in.waw.pl> wrote:
Hi,
On Mon, Feb 24, 2020 at 05:48:36PM +0100, Pierre-Yves Chibon wrote:
> For the changelog, we believe we have a potential good solution:
> - The changelog will be automatically generated using an external `changelog`
> file as well as the commit history
...
> If you wanted to edit the changelog, you would:
> - Generate the changelog locally via a command like:
> `fedpkg generate-changelog > changelog`
> - Edit `changelog` as desired
> - Commit and push the changes
This means that a separate commit needs to be done *after* on top
of the commits doing the actual changes. It's a bit disappointing, but
on its own would not be too bad, since we can have fedpkg provide a
higher level command that combines generate-changelog and build...
One important feature will work:
being able to cherry-pick commit between branches w/o spurious
conflicts. As long as the "real" change to the spec file are done in
separate commits, and the changelog commit is another commit on top,
then when cherry-picking to another branch, the "real" commits would
be cherry-pickable, and then the changelog commit would be recreated
using the automation, OK.
But it doesn't work quite as nicely with something similar: merging
branches. A simple 'git merge' would result in conflicts.
Also, if an amendment to the changelog is done, and the same change
needs to be done in the changelog in a different branch, trying to
cherry-pick the fix commit would most likely result in a merge
conflict.
Considering these three drawbacks (separate commit step and resulting
log noise, merge conflicts), I'd very much hope for a solution where
the changelog is never stored in the version control, and is always
autogenerated at srpm creation time. We should never try to chery-pick
commits that have changelog entries with actual date or e-v-r texts,
since this will inevitably lead to merge conflicts.
A different approach:
- we have 'fedpkg generate-changelog' (which does all the git log
extraction that was described, I think that part is OK),
- the output from this command included in the srpm at srpm generation
time and never committed to version control,
- the output is annotated with the source commits hashes, so we can
see where each line came from.
At any time, the packager can run 'fedpkg generate-changelog' to see
how the output looks like. If they see something they don't like, if
the commits haven't been pushed out yet, they can immediately run
'git commit --amend' and recheck. If they have been pushed out, an override
to the changelog could be committed as part of a commit message text.
Git-changelog-suppress: ad5555b42e
or
Git-changelog-suppress: ad5555b42e..efefedeadb
or
Git-changelog-replace: ad5555b42e
Some other text with typos fixed that completely overrides whatever
was generated from ad5555b42e.
or
Git-changelog-append: ad5555b42e
(additional clarification for commit ad5555b42e, e.g. bug #12345)
This would have the following advantages:
- git log is the sole source of truth
- there are no cherry-pick or merge conflicts
- there is no separate "now I'm done and I need to do another commit
before building" thing.
The assumption is that those Git-changelog-* macros would only be
used occasionally, if the bad changelog entry was not noticed before
pushing the changes out.
(One nitpick: when cherry-picking between branches, hashes of the
cherry-picked commits change, so "ad5555b42e" in the example above
would stop working. This is handled by using 'git cherry-pick -x'.
'fedpkg generate-changelog' would look at any hash in a
"(cherry picked from commit ...)" line.)
Hello Zbyszek,
it's good that it solves conflicts when cherry-picking and merging and
git log is the source of truth but simply dropping a line that i don't
want in the changelog or appending something to it seems to be quite
painful to do.
One advantage you mention is:
- there is no separate "now I'm done and I need to do
another commit
before building" thing.
But if you want to modify the automatic product, you
would need one or
more additional commits to do that.
Imho, one would prefer to be able to do that simply by editing a text
file (even if temporary). Annotated tags give you that ability by
design - the tag annotation can be prepopulated and then freely
edited, which is much more pleasant in my opinion. It doesn't clutter
commit space and you can point other branches to that particular
annotation by merging if desired. But the cherry-picking workflow, on
the other hand, would require creating a new tag specific for that
branch (that would suggest the tags should contain branchname/%dist at
the end as fedpkg does it now). That's were things start getting
clumsy unless there is something like fedpkg build --annotation-from
f31 to make a new tag with the same content as is the one in f31
branch, push it and build.
Similar workflow with git notes should be imho also considered.
I also wonder whether: "Changelog generated must be editable" from
the document means after pushing or before pushing and whether it is
such a hard requirement. If I make some "critical" mistake like
referencing wrong CVE, it might be better to create a new changelog
entry and new release, that will otherwise contain no changes and will
simply provide a message of type:
- Changelog correction for release 1.5.1:
- 1.5.1 does _not_ fix CVE-2020-3123
- 1.5.1 _fixes_ CVE-2020-3124
I think cases when a maintainer wants to do something like this are
rare and if they happen it might be better to model that case like an
"email communication", rather than "into the past mutable channel".
In
case of annotated tags, that would mean some commits would have two
attached (rare situation), the second one with the correcting message.
With respect to automatically generated release numbers, the machinery
in rpkg-util would handle it correctly, idk about other approaches.
One disadvantage of annotated tags might be that you cannot merge them
from pull requests but on the other hand, one can at least provide
"the prepopulated content" (e.g. simply by messages in the commits
being merged) that maintainer can then use when the tag is being
created.
I am talking about annotated tags because i am familiar with that
approach and i don't have that much to say about other approaches at
the moment.
>
>
> As how to hook this up with rpm,
> looking at
https://pagure.io/packaging-committee/pull-request/942#comment-108542,
> a macro like %generate_changelog could be provided that would
> simply shell out to 'fedpkg generate-changelog'.
>
>
> I'll comment separate on the -release part.
>
> Zbyszek
> _______________________________________________
> devel mailing list -- devel(a)lists.fedoraproject.org
> To unsubscribe send an email to devel-leave(a)lists.fedoraproject.org
> Fedora Code of Conduct:
https://docs.fedoraproject.org/en-US/project/code-of-conduct/
> List Guidelines:
https://fedoraproject.org/wiki/Mailing_list_guidelines
> List Archives:
https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org