Re: [docs] Version bump before release

[Michael Opdenacker <michael.opdenacker@bootlin.com>]

Greetings,

On 3/18/22 07:47, Quentin Schulz wrote:
> Hi all,
>
> On March 18, 2022 1:04:32 AM GMT+01:00, Michael Halstead <mhalstead@linuxfoundation.org> wrote:
>> Hello,
>> In the past we've correctly bumped the versions in the yocto-docs release
>> branches before the release build and I only need to update the master
>> branch to update the switcher on the website. This doesn't happen reliably
>> though and we've been having to patch the build system to make the docs
>> build correctly.
>>
>> Ideally all that would be needed at release time is a patch like
>> https://git.yoctoproject.org/yocto-docs/commit/?id=78545b8f42657c21bc3cac96429d3950b07a3aca
>> to update the website.
>>
> For the new releases (not the dot releases), it is essential this patch is merged with correct infos before tagging, specifically the poky.yaml file.
>
> For dot releases, what matters is the bump of the dot release in poky.yaml, the rest of the changes aren't that important because it's impossible to always keep it up-to-date.
>
> releases.rst and switchers.js are taken from master for all builds anyways by yocto-autobuilder-help so we don't technically have to worry about those making it before tagging day. Those need to make it to the master branch as soon as possible though (basically after tagging).
>
> Two changes to conf.py need to be done too for releases. current_version needs to be bumped and bitbake_version to be set.


Some of the mess is probably my fault. I didn't want to update *master*
to refer to releases that didn't exist yet, because this causes warnings
on the documentation website. However, I realize there should be no
issue updating the release branches (such as
https://docs.yoctoproject.org/dunfell/, which I believe are not
advertised on https://docs.yoctoproject.org/), so I was wrong to apply
the changes only after the release was out.

My apologies!

Let me try to understand if I understand the desired workflow correctly:

  * Prior (weeks before) to a future new release, create a new release
    branch on "yocto-docs", e.g. "kirkstone"
  * Update documentation/conf.py (version specific) and
    documentation/poky.yaml in the release branch (e.g. "dunfell")
    according to the upcoming release (e.g. "3.1.15")
  * Before making the release, check in the content of conf.py that
    current_version is NOT dev and that bitbake_version is set. If
    current_version is set, extract it and make sure it's used in
    poky.yaml too. Also check that the YOCTO_DOC_VERSION_MINUS_ONE
    setting in poky.yaml corresponds to the number of the latest n-1
    release.
  * Make the release. I guess, when we have a new release, this means
    that a new branch for BitBake was created.
  * Make sure
    https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-build
    supports the new BitBake branch.
  * Add new tags to the branch (e.g. "yocto-3.1.15" + "dunfell-3.1.15").
    Isn't the "yocto-" tag sufficient by the way?
  * Update the following files in master:
      o documentation/conf.py
      o documentation/poky.yaml
      o documentation/releases.rst
      o documentation/sphinx-static/switchers.js

Would this be a correct workflow? I propose to keep this in a wiki page
by the way, so that updates and notes are easy to manage.

Thanks,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com