Release notes procedure

[joaquintides]

In the old website, release notes are produced collectively by authors submitting PRs to this Quickbook file (or the equivalent one for the release at hand):

https://github.com/boostorg/website/blob/master/feed/history/boost_1_85_0.qbk

We need to implement a similar procedure for the new website. The ideal solution would be one where release notes are compiled automatically from individual contributions within each library repo, but for the moment being we prefer to have something conservative and minimally disrupting with respect to the protocol in place, meaning there should be a a per-version file where authors can submit their PRs.

As for the particular question of which markdown language this document should use, we can have:

• Quickbook (as now),
• Asciidoctor, or some other alternative.

I don't have a strong opinion here, if the language is anything other than Quickbook authors will probably adapt without problems.

[sdarwin]

A proposed idea for the release notes procedure:

• Create a top level directory release-notes/ in https://github.com/boostorg/website-v2-docs
• Manually convert the most recent release notes, from https://github.com/boostorg/website/blob/master/feed/history/boost_1_85_0.qbk to release-notes/boost_1_85_0.adoc, as an example page.
• In https://github.com/boostorg/website-v2-docs/blob/develop/.github/workflows/publish.yml , copy the jobs that are building and publishing the user-guide and contributor-guide so that release notes are also rendered and uploaded, to a release-notes folder in S3. Should it use antora, or plain asciidoctor?

[alandefreitas]

@PeterTurcan Can you open a PR with the adoc template?

[sdarwin]

From Alan: website-v2 is able to process adoc files.

Checking,

def convert_adoc_to_html(file_path, delete_file=True):

def process_adoc_to_html_content(content):

Very convenient.

That means GHA can just upload adoc files to S3 as-is.

[sdarwin]

More technical details about the same topic.

Currently, html-formatted release notes are imported from github. https://github.com/boostorg/website (the original website). The code to accomplish that is in versions/releases.py.

def get_release_notes_for_version(version_pk):
    """Retrieve the release notes for a given version.

Going forward, new release notes will be available in a different location, which is the S3 bucket STATIC_CONTENT_BUCKET_NAME. That bucket is already used for archives, site-docs, and site-pages. The folder release-notes/ will contain the release notes.

get_release_notes_for_version() should first check if the release-notes for a particular boost version are in s3://STATIC_CONTENT_BUCKET_NAME/release-notes/ . If yes, retrieve those. Otherwise, fallback to the existing behavior of going to https://github.com/boostorg/website.

Per an earlier comment, website-v2 is able to parse Asciidoctor files. The content in S3 will be in adoc format. Convert to html when reading the files.

[kennethreitz]

This is extremely nuanced. I believe I saw a good solution to this mentioned on Slack. Does anyone recall the MVP (minimum viable product) we quazi-settled on?

[sdarwin]

Hi @kennethreitz ,

Here is a sort of high-level overview about how release notes are working currently.

boost.org:

• For the previous https://boost.org, developers manually update a file with the release notes. That is checked into github. https://github.com/boostorg/website
• At the webserver (wowbagger), the full website repo is downloaded, and the quickbook version of the release notes file is parsed and formatted to html. Then, the html version is also checked into the github repo.
• Visitors of https://boost.org see the html version of the page.

boost.io:

• When a release is published, boost.io retrieves the html version of the page from the boostorg/website repository, and stores that in the database. It's displayed on a page such as https://www.boost.io/releases/boost-1-85-0/

future boost.io:

• The developers will still modify a page of markdown, and check that into github. The idea is that's now asciidoctor format instead of quickbook.
• The process is in place to upload this page to S3. It's already working.
• What remains: To collect the file from S3, and display it on a release such as https://www.boost.io/releases/boost-1-85-0/ (or rather, 1-86-0)

[sdarwin]

thinking about it more... S3 was added there in the last steps to facilitate processing/rendering of the asciidoctor page, so that a rendered page would be uploaded to S3.

However, github actions is actually uploading the asciidoctor page as-is. (see earlier comments about why)

That means, if it's easier, you can retrieve the release-notes from github https://github.com/boostorg/website-v2-docs

[kennethreitz]

I've reviewed the proposed steps and they look solid. Creating a release-notes/ directory and manually converting the latest notes to boost_1_85_0.adoc is a great foundation.

Integrating this into our GitHub Actions workflow to render and upload to S3, then ensuring the website fetches and displays them, will streamline the process and enhance accessibility.

This will make the release notes more accessible and organized, fitting perfectly into our workflow. Excited to see this implemented!

[kennethreitz]

Adopting Asciidoctor for generating release notes offers significant benefits over Quickbook. Asciidoctor reduces boilerplate, streamlining the creation process, and enhancing flexibility.

• This approach integrates seamlessly with GitHub Actions (yay!), enabling automation for building and deploying release notes.
• Converting existing Quickbook files to Asciidoctor is straightforward, ensuring continuity.
• By storing notes in an S3 bucket, we centralize access and improve distribution.
• This change minimizes disruptions while modernizing our workflow, enhancing both efficiency and documentation quality.