Documentation Semantic Versioning about techdocs HOT 15 CLOSED

Hey, should i take this one?

from techdocs.

I'm not sure how to find the most recent version. Any suggestion?

Currently we have a link to the latest patch version (https://github.com/accordproject/cicero/releases/v0.20.2), so that could be just the latest major/minor version (https://github.com/accordproject/cicero/releases/tag/v0.20.0)

oh ok, that would work. the word latest confused me there. I'll do that.

The Pre-Release Versions would have a link to the release notes, which would be displaying the most recent on top (https://github.com/accordproject/cicero/releases)

Cool! That works too. Thanks for the clarifications.

from techdocs.

@irmerk Why would we remove the patch version?

from techdocs.

I believe this was based on a discussion in a technology working group call, thinking the documentation could follow the major/minor versions as a form of LTS and not needing to update it with every patch fix.

from techdocs.

I believe this was based on a discussion in a technology working group call, thinking the documentation could follow the major/minor versions as a form of LTS and not needing to update it with every patch fix.

I've been making patch release versions of the documentation (some improvements go in on patch release from time to time), should I stop doing that?

from techdocs.

If we align the doc versions with the Cicero versions (which we should), then I don't think a patch version update of Cicero should require a doc change (if it does it is probably not just a bug fix). For changes/fixes to the docs themselves I think they can go in unversioned (they should apply to all 0.20.* Cicero releases for example).

from techdocs.

If we align the doc versions with the Cicero versions (which we should), then I don't think a patch version update of Cicero should require a doc change (if it does it is probably not just a bug fix). For changes/fixes to the docs themselves I think they can go in unversioned (they should apply to all 0.20.* Cicero releases for example).

Right... I think I get the idea now. All 0.20 versions should be compatible, so improvements to the documentations apply to all of them, independently of the patch number.

Ok thanks for explaining.

from techdocs.

@irmerk @dselman How far back to we need to keep versions for? Can we "reset" a bit and start with versions 0.13 and 0.20 ?

from techdocs.

There is one other consideration. In order to cut a new release with docusaurus, we need to increment the version number.

This means that either:

• we should make changes to static versions of the docs to avoid increasing the patch version in Docusaurus just for docs updates.
• Hide the patch version in the front-end in the docs to avoid confusion as Cicero and Docs patch versions diverge

from techdocs.

@irmerk @dselman How far back to we need to keep versions for? Can we "reset" a bit and start with versions 0.13 and 0.20 ?

Interesting, yeah I suppose we should only keep documentation for the versions we currently support. I would think that at the pace we are going, and especially expect to be going in the future, having a current version and 1-2 previous versions seems reasonable. Similar to node, supporting a version for 1-2 years?

• Hide the patch version in the front-end in the docs to avoid confusion as Cicero and Docs patch versions diverge

I think this was the line of thinking that lead to this issue in the first place, and would be my preference.

from techdocs.

@irmerk @dselman How far back to we need to keep versions for? Can we "reset" a bit and start with versions 0.13 and 0.20 ?

Interesting, yeah I suppose we should only keep documentation for the versions we currently support. I would think that at the pace we are going, and especially expect to be going in the future, having a current version and 1-2 previous versions seems reasonable. Similar to node, supporting a version for 1-2 years?

The reason I am asking is that I can't think of a clean way to re-write the version history, except for manually regenerating versions (for reasons related to @mttrbrts coment). If we don't have to go back too far in time, this is definitely less daunting.

Also, I really am not sure that the version numbers in Docusaurus have been very cleanly aligned with Cicero versions in the past, so for older versions it's unclear exactly what they document.

Once we have a clean version based on the proposed approach, I think it will be fine to maintain as suggested moving forward.

from techdocs.

There is a bit of a conflict of interest between this requirement: only maintaining the documentation based on the the major.minor distinction, and the requirements to have pointers to the release notes in the versions table (see e.g., #75)..

What do people want the table to contain if we remove the patch number?

1. No more pointer to release notes?
2. Only pointer to the initial release notes?
3. Only pointer to the last release notes?

Of course another option is to actually re-tag the documentation on patch releases, which is less work.

Guidance would be welcome.

from techdocs.

We could possibly have the Current Version (Stable) have a link to the most recent major or minor release notes. And Pre-Release Versions have a link to the release notes instead of a particular release's notes.

from techdocs.

We could possibly have the Current Version (Stable) have a link to the most recent major or minor release notes.

I'm not sure how to find the most recent version. Any suggestion?

And Pre-Release Versions have a link to the release notes instead of a particular release's notes.

I'm not sure I understand this.

from techdocs.

I'm not sure how to find the most recent version. Any suggestion?

Currently we have a link to the latest patch version (https://github.com/accordproject/cicero/releases/v0.20.2), so that could be just the latest major/minor version (https://github.com/accordproject/cicero/releases/tag/v0.20.0)

The Pre-Release Versions would have a link to the release notes, which would be displaying the most recent on top (https://github.com/accordproject/cicero/releases)

from techdocs.