Release process and versioning

[ClemensLinnhoff]

Describe the problem

At the end of this project we need to do a release 1.0.0.
I would assume we use the GitHub release functionality and set a release tag v1.0.0 to the last commit in the main branch at that time.
Since at that point there will be only one version of the standard, there will also only be one version of the documentation.
However, over time, there will be a current development in the main branch after 1.0.0 and later also future version.

Describe your research

In OSI you can select different versions of the standard and also the current development state on the upper right side of the documentation page, see screenshot:

We seem to have something similar in the OpenMATERIAL 3D documentation on the lower left side. But this currently says 1.0.0, which is not released, yet.

I think the main issue will be the automatically generated ASCIIdoc files from the JSON schemas. Currently, this is done by calling a python script in the build pipeline here.

Ask your question

How will this work with multiple versions of the standard?

[martinfiebig]

Hi @ClemensLinnhoff, with Antora, there are basically two ways to have different versions of the documentation, by using branches or by using tags to store the older versions of the content. Both ways, the documentation will then be generated from the old version(s) of the content. This should also work for the generation of the AsciiDoc files from JSON - I will test this in my forked repository and report back.

[martinfiebig]

Hi @ClemensLinnhoff, I've tested the handling of multiple versions in my fork and unfortunately, the generation of the AsciiDoc files from JSON does not work for older versions, only for the current one. So for the older versions, the files would need to be generated elsewhere and then be stored in the respective branches of the older versions.

[ClemensLinnhoff]

What would you recommend what would be the best way to do this?
How does it for example work with the OSI Doxygen documentation, which is also generated from code? Is this somehow done in the Antora image at ASAM?

[martinfiebig]

Hi Clemens, we will look into the workflow for OSI. The antora build in OSI is however much more complicated than in OpenMATERIAL, since OSI uses multiple repositories to store and generate the documentation. So I'm not quite sure, if we can take over the mechanisms used in OSI.
We will test that and come back with possible solutions.

[ClemensLinnhoff]

How about we create a deploy branch. Everytime a branch is merged into main, the state can be pushed to the deploy branch incl. the generated asciidoc files. The release tags can then be set to the respective commits in the deploy branch and the documentation can be fully generated from that branch.