Release Notes as a separate document

[lzap]

Hello,

I would like to start moving our Foreman installation guide from markdown to asciidoc hosted on https://docs.theforeman.org but as the first step, I would like to tackle one particular problem - release notes. I see several problems with the current state:

We currently present release notes as the first chapter in our installation guide: Foreman :: Manual and one of the problems is this is quite lengthy document. While this is definitely important stuff for upgrading, full list of all redmine tickets is quite lengthy and users need to scroll down quite a bit.

Since the list is so lengthy, we tend to keep only release notes for the particular release on the same page, however we know that majority of our users stay on a particular release for some time and then upgrade in batches (e.g. from 1.18 to 2.1). Then they need to switch over from version to version. Not a big deal but worth mentioning.

Finally, our workflow when editing release notes is a bit tricky as multiple people contribute to this and we need to branch off documentation early. People who want to contribute to release notes need to use one branch, people contributing to the manual itself need to make changes in master branch (gh-pages) and the release.

I would like to propose creation of a new document called “Release Notes” with one chapter called Foreman and subchapters for each individual versions. We would link those notes from the current manual, and in the future from the new manual as well. There would be no need to branch off early as master branch would be always “up to date” including all the historical versions. Thanks to dedicated chapters and subchapters, the document would be readable and usable also for users who are planning upgrades over multiple versions.

For release notes for 2.3 I will create a discourse thread (wiki) until we decide if this proposal is good enough and I’d like to start working on this immediately so it’s ready for 2.3. If people don’t like this, I will then fallback to the old workflow branching off early.

[lzap]

Release notes and headline features for 2.3

Release notes for 2.3 This section will be updated prior to the next release. Headline features Release Notes Deprecations Upgrade warnings Report creation via /api/v2/config_reports/ REST POST no longer returns the full report for performance reasons. Only basic metadata like database ID is returned, when full report is needed query the same REST resource via HTTP GET method to fetch it. More info at https://github.com/theforeman/foreman/pull/7987 Contributors We’d like to thank the followi…

[ezr-ondrej]

Make sense to me
Where would the document lived though?

[tbrisker]

@lzap

Finally, our workflow when editing release notes is a bit tricky as multiple people contribute to this and we need to branch off documentation early. People who want to contribute to release notes need to use one branch, people contributing to the manual itself need to make changes in master branch (gh-pages) and the release.

That isn’t accurate. All the release notes are in the same main branch, just under different folders by version. In fact, I find it quite useful that people can add notes (mostly upgrade notes and deprecation warnings) to the next version by adding them to the nightly manual throughout the whole release cycle instead of waiting for the release itself to start.
The major part of the release notes section (the list of all changes) is automatically generated from
redmine as part of the release process, so there is not much point in having it updated all the time.
In the past we had a different process, where there wasn’t a nightly manual and the release notes were only created when working on the release, leading to a lot of forgotten deprecations and upgrade warnings as well as extra work for the release owner.

@lzap

We currently present release notes as the first chapter in our installation guide: Foreman :: Manual and one of the problems is this is quite lengthy document. While this is definitely important stuff for upgrading, full list of all redmine tickets is quite lengthy and users need to scroll down quite a bit.

If we had a page with all historical release notes, it would also get very long quite quickly, perhaps even more so than the regular manual. Maybe we should change the layout of the manual to only load one section at a time instead of one long page (similar to how the Katello manual works)?

@lzap

For release notes for 2.3 I will create a discourse thread (wiki) until we decide if this proposal is good enough and I’d like to start working on this immediately so it’s ready for 2.3. If people don’t like this, I will then fallback to the old workflow branching off early.

from me to this proposal. Having to go search for a post in discourse is much more difficult than opening a pr to directly update the relevant section. It also prevents the review process we have for PRs to ensure that the release notes actually make sense and are well worded. Also it’s too late for 2.3, the first version of the 2.3 manual will be released with the first RC, which is expected next week.

[lzap]

@tbrisker

it would also get very long quite quickly

That’s why I suggest it as a separate document. I am not saying we must not delete old version from it, but we can affort 5-10 historical versions as 5-10 chapters perhaps. You can’t do this today, well you can but that would be even worse experience.

@tbrisker

Maybe we should change the layout of the manual to only load one section at a time instead of one long page (similar to how the Katello manual works)?

Manual should be a paper-friendly thing, a printable text. Something you can download as a PDF to your reader.

@tbrisker

Having to go search for a post in discourse is much more difficult than opening a pr to directly update the relevant section.

Okay if you don’t like it, I will turn the discourse post into a PR, no changes in the workflow then. Still I think separate document would be cleaner experience.