-
Notifications
You must be signed in to change notification settings - Fork 49
[?w] changelog process for collections #18
Comments
Release Note / Changelog Fragment Ideas for CollectionsWe have a continuing need for changelogs (or release notes) to cover:
Reviewing similar projectsWe've looked at how RHEL, Fedora, and OpenStack handle this scenario. These projects are built from a subset of projects/components that are similar to how ACD will be created. RHELRHEL is a release that combines a set of subprojects (e.g. gnome, linux kernel, qemu, etc). Looking at hte RHEL release, it includes Release Notes and Red Hat Errata. The Release Note focuses on new features, bug fixes, and known issues since the last RHEL release. It does not include a combined list of changelogs etc from all the subprojects upstream that make up RHEL. The errata is a more detailed list of bugfixes and upstream subprojects included in the RHEL release, but again, does not include details on all the changes that happened in all the subprojects. RHEL uses internal tools the generate the release notes and errata. FedoraFedora is upstream of RHEL and is also built from a set of upstream subprojects. Fedora includes release notes and ChangeSet. One package example (RPM) shows a link to the upstream release notes that are a summary of changes from one major release to another (e.g. RPM 4.14x to RPM 4.15.0) That RPM release note appears to be manually created. Since Fedora upgraded from RMP 4.14 to RPM 4.15, the release notes upstream show the full set of changes that were manually added to the release note. Another example, the gnu c library - the Fedora release notes have high-level changes and point to the upstream NEWS section for the gnu c project for details. This news section seems to be partly manually written, and partly a script-generated list of bugfixes. OpenStackOpenstack uses the reno to create a release note for each individual subproject. There is a main page that lists all the individual projects and links to their release notes. Openstack subprojects can release on a slower cycle than the Openstack release so in that sense, they are different from ACD, which is a compilation of collections that may have released multiple times between ACD versions. That said, |
ansible-collections/community.kubernetes#40 is also discussing this... |
Changelog tool optionsThis comment summarizes the changelog tools under investigation. All tools must:
OpenStack renoThe reno project:
towncrierThe towncrier project:
|
We should also consider updating the current changelog tool we use to work with collections. We used
That last one is critical, as it's embedded into I'm sure there are other features I'm forgetting as well, but I think I covered most of the major ones. |
I prefer Ansible's tool and towncrier over reno, since they don't enforce a specific git workflow. Ansible's tool also has the advantage that we can easily adjust it to do exactly what we want. And people working with Ansible really should be familiar with YAML files :) |
@felixfontein can you clarify the git workflow you are talking about? I think in order for use to be able to gather fragments from multiple collections (and multiple releases within the collection) to get a complete ACD release note, we will need those git release tags within the collections. |
@samccann The current tool tracks every fragment that goes into a release in a |
For those not familiar with the current tool, here's a basic idea of how it works in ansible/ansible:
Since steps two and three are separate, it allows for things like generating a detailed changelog of pre-releases and then collapsing the pre-release entries for a GA release. This could also be used to facilitate processes such as combining changelog fragments from multiple collections and generating a comprehensive changelog. The original fragments would be used, yet the resulting changelog output could be, if desired, organized and formatted differently. |
Step number two is also where the tool creates entries to track new plugins and modules in the YAML file, which is why fragments do not need to be manually created for those. No need to worry about forgetting to document a new plugin or module. |
Ansible's tool (let's give it a name) because it has all we need and we used it before. |
ansichlog? :) |
Whatever we choose, I just want it to be simple, and ideally also have some way of linting (if possible) so whoever does releases for collections doesn't have to sit around manually cleaning up stuff at release time. It's already a larger burden pushing out new releases for collections than roles, and would be especially bad if we can start automating releases but those releases get broken due to bad fragments. |
Will it be a must and be forced for all collections in ACD? In Openstack Ansible Collection we consider to use reno, as it's Openstack native tool for changes. |
Not just RST. It can be any text file and the changelog rendering can be templated w/ jinja2. |
FYI for reno fragments, ansible/ansible does this in CI. For towncrier, I have a GitHub App enforcing the presence of the fragments in PRs. |
Changelog Idea ComparisonGoal: provide a unified changelog for ACD NOTE: Current thinking is that the porting guide for ACD would be handled the same as we handle it today for ansible (core) - that is, we provide the shell of a porting guide and each collection owner is responsible for putting in the details necessary for an ACD user to upgrade from the current ACD version to the new ACD version (for their respective collection). #1 Require ansible/ansible changelog processPros:
Cons:
#2 Recommend ansible/ansible approach or collection owner must provide changelog file per release in ansible-defined format.Pros:
Cons:
#3 Same as #2 but includes individual changelog fragments#4 Link to changelogs within collectionsPros:
Cons:
#5 Same as #4 but have a manual release note for ACD that collection owners can add important changes to.Pros:
Cons:
|
My peronal ranking (best to worst): 2, 5, 4, 1 (I intentionally left 3 away)
|
I'm a big fan of reno. And have wanted to enable it on network collections for some time. |
+1 for reno, it'll be also a straighforward change for network collections/tox |
I prefer # 2 |
@samccann you may want to create a poll via https://github.com/apps/polls next time |
@pabelanger @danielmellado Note: reno is only sort of an option. #2 would require collection owners to create some code so that reno can output a machine parsable changelog that our tools can then pull in to make a unified changelog/porting guide. #3 would require the same but at the fragment level instead of a single output file (there would probably need to be an additional metadata file as well that pulled out what fragments belong to which release.). #4 would let you use reno and you'd manually tell us what the link to your reno-generated changelog is so that we can add the link to our changelog/release notes. #5 Would be the same but docs would merge manual requests from collection owners to highlight things that collection owners considered important enough to show up in the ACD changelog. |
@jimi-c as I understand it, 3 vs. 2 only means whether the fragments have to be there for ACD to consume them. For creating changelogs, I really prefer fragments as well, but I don't mind if collections using other tools provide the compiled changelog as a combined YAML file and not as a set of changelog fragment files. |
Summary of voting/commentsBased on the comments and actual votes, the top vote-getter is: 2 - recommending the ansible/ansible approach (and the assumption that we'd turn this into a tool that collection owners could use).
|
My vote is 5 first, then 4 then 2. I much prefer direct linking so I can see just what I want. I don't need a giant list that is hard to scan about changes. Having important changes noted would be nice, but if I don't care about AWS but do care about Azure, I should just be able to dive into their logs. |
This is a mockup of what an ACD level changelog file might look like - https://github.com/samccann/ansible/blob/test-changelog/docs/docsite/rst/changelog_acd.rst |
BTW
Would be good to officially determine a proper changelog message format:
|
I tried to generalize Ansible's changelog generator to collections; here's my current state: https://github.com/felixfontein/ansible-changelog/ I've ran it for community.general (with In particular:
|
reno/towncrier etc users - can you please evaluate the changelog YAML container file in the above comment? That is similar to what we would want collection owners to produce if they don't use the proposed changelog generator based on ansible/ansible. (with the final fallback of just giving us a link to whatever the collection owner has) |
ansible/ansible#69268 , it's a PR about changelog entry's format i mentioned above |
I also created a test collection with a changelog spanning multiple |
ansibulled has been renamed to antsibull, and can now be installed via pip. Part of antsibull is antsibull-changelog, the changelog generator! Here is some documentation for collection maintainers on using it. If you are using another changelog generator and want to output a ACD-compatible changelog.yaml file, the format is documented here, and antsibull includes a validator ( |
The changelog generator was moved to https://github.com/ansible-community/antsibull-changelog/ and can be installed via pip (https://pypi.org/project/antsibull-changelog/). The docs are now here, and the changelog.yaml syntax is here. |
|
@felixfontein - seems like this issue can be resolved now that https://pypi.org/project/antsibull-changelog/ is live? |
@samccann I think so! Thanks for reminding us :) |
Once we've answered the above, we can look at tooling that exists.
The text was updated successfully, but these errors were encountered: