jaegertracing
[IA] Questions about versions,`latest`, and `next` releases
Information Architecture questions for @yurishkuro
(1) The Hugo config defines two "latest" versions. This makes me wonder: are the docs being evolved only in v2 now, or might there be more v1 versions?
More generally, will there ever be more than one actively maintained version of the docs -- more than one latest? Currently, v1 & v2, but in the future it might be more than two.
(2) The site has these two sections:
- https://www.jaegertracing.io/docs/next-release
- https://www.jaegertracing.io/docs/next-release-v2
Do you still want these sections to exist post-migration as is? Are they (both) meant to be published in production? This is somewhat related to question (1). I have more followup questions, but let me start with this.
Oh my, I'm seeing that the doc structure is created by front-matter entries, rather than by the use of Hugo sections (nested folders). That will be quite something to reorganize!
(3) Do you want to migrate all doc versions?
(1) The Hugo config defines two "latest" versions. This makes me wonder: are the docs being evolved only in v2 now, or might there be more v1 versions?
this is a great question - the plan is to fully sunset Jaeger v1 at the end of 2025. We probably still want to preserve the v1 docs at that point, but we could do it differently, by running the existing website under a separate subdomain (like docsv1.jaegertracing.io), and only worry about upgrading v2 docs to docsy.
Regarding v3 etc, I wouldn't worry about it. It took us almost 10yrs to release v2, and it was a major change of the architecture, I don't see us doing that again any time soon.
As for next-release, I prefer we keep that capability, as it allows merging PRs to docs that only make sense once the next release happens. The actual numbered versions are just snapshots we take at the time of the release. Maybe docsy has a different way of fixing the versions.
next-release is accessible in prod, it's just hidden from the versions menu (but it's visible in dev mode).
@yurishkuro - thanks for clarifying about the latest releases. It makes sense.
(A) On the website, /docs/latest maps to the latest major release version. I'd like to propose that the Hugo config param names match this interpretation. What do you think of replacing/renaming the param in the Hugo config so that:
latestis renamed tolatestV1, or better yetprevlatestV2is renamed tolatest, matching the semantics of the website path/docs/latest
I'm not saying that I'll actually do these changes, but I'm trying to start forming a model of how doc versions will be handled in the Docsy-based site.
I also understand the usefulness of the next-release folders. It is common to have them. My main question was about their content-folder names, and how to integrate them more uniformly.
(B) What do you think of using the following content/docs subfolder names instead:
1.next2.next
Or maybe {1,2}.draft instead of {1,2}.next?
If not, can we at least use next-release for v2 and use next-release-v1 for the old release stream so as to be consistent with (A)?
I don't have objections to these. The current latest and latestV2 naming came from trying to minimize the changes when introducing v2. worth
(1) The Hugo config defines two "latest" versions. This makes me wonder: are the docs being evolved only in v2 now, or might there be more v1 versions?
currently both v1 and v2 are evolving, since we do parallel releases like Release v1.69.0 / v2.6.0 https://github.com/jaegertracing/jaeger/releases/tag/v1.69.0
(side note - we also need to upgrade the backend release process to make v2 the primary version)
There are no GitHub releases of the docs it seems: https://github.com/jaegertracing/documentation/releases is empty. As for tags, the last is 1.62 (see https://github.com/jaegertracing/documentation/tags). So I think that all GH releases happen via / at https://github.com/jaegertracing/jaeger/releases?
Is https://github.com/jaegertracing/documentation/blob/main/scripts/release.sh still relevant, or can I make site config changes and not worry about it?
release.sh in the docs is what makes the release - it creates a snapshot of next-release dir into a numbered dir and does some config manipulation plus some url rewriting to the main repository so that the GitHub links are permanent.
You can see the release process described in RELEASE.md (backend, ui, and docs repos have it)
From https://github.com/jaegertracing/jaeger/tags, I get the impression that you put out a release every month, some time during the first week of the month? Is that correct? (Just so I know how much of a window I have between releases.)
For my reference: https://github.com/jaegertracing/jaeger/blob/main/RELEASE.md, https://github.com/jaegertracing/documentation/blob/main/RELEASE.md
Thanks for answering my questions. I'll have to think more about a possible new IA / content organization. Ideally, we shouldn't have any config for the versions in hugo.yaml. It can (or should be) all be derived from the files and folders under content/docs. Regardless of the config, I think that I'll have to experiment a bit with some content directory organizations to see how well it can work under Docsy.
I get the impression that you put out a release every month, some time during the first week of the month? Is that correct?
That is correct, we release monthly.
Ideally, we shouldn't have any config for the versions in hugo.yaml
Yes, there's no strong reason to have them hardcoded, they can all be computed. But the versions in the config are automatically updated by the script, so it's not a big deal to have them there if they make the templating code easier.
@chalin does docsy have a blessed / recommended way of managing versions? We could adopt it if necessary. It was my understanding it supports either sub-directories (what we already use) or git branches as the sources of versions.
In https://github.com/jaegertracing/documentation/issues/935#issuecomment-2977450841 @yurishkuro wrote:
do you have an example of "default" way docsy does versioning? I see that k8s does it via subdomains.
Yes, K8s does subdomains, because it would be unmanageable otherwise. https://etcd.io does subfolders.
I'd like to propose that we get a base port of the website first, and then we can assess whether you'd like to go the subdomain or subfolder (the current solution) route.