Given that each of the instances is labeled by release name, I would assume https://doc.wikimedia.org/codex/main/ would continue to correspond to the state of the "main" branch. Perhaps instead we could add a latest tag that gets updated with each new release to point to the same commit as the release?

I think publishing the latest docs at https://doc.wikimedia.org/codex/latest/ makes sense, and that we should point to that as the canonical version.

I think we could achieve this by:

• As @DannyS712 suggested above, creating a git tag called latest, and updating it every time we do a release.
  • I think updating a tag requires force-pushing, and we'd have to remember to update it every time we do a release, which is not the cleanest approach. So we may want to look for a better way to automate this (perhaps in the PHP code that runs the docs site), but a tag will work for now.
• To display a banner on non-latest version of the docs site, we could have the docs site code look at whether the root URL it's been given ends in /latest/, or alternatively whether the`ZUUL_BRANCH` environment variable is present and set to latest (then later we could clean that up by moving that logic to the integration-config repo and having it pass something like CODEX_DOC_STABLE=1)
  • One issue with this approach is that it would erroneously show the warning banner on https://doc.wikimedia.org/codex/v1.2.3 , even if 1.2.3 is the latest version. But I don't think there's much we can do about that, because the docs site for a release tag is static and is built at release time. If we care about this, we could hedge the message and say "this may not be the latest version"
• I would also suggest adding the version number to the docs site in a prominent place (both for the latest and the non-latest docs). It should be easy to obtain programmatically through require( 'path/to/codex/package.json' ).version

I'm not completely convinced that the default demo shouldn't show the latest and greatest. I'd rather be very clear to show what version the demos are based on (and maybe put latest release as alternative navigation path prominently).

This task has been moved to the "needs refinement" column since there are some details that need to be further clarified.

• How do we indicate to users which version of codex the docs are referring to? This should be visible on every page
• Do we need to allow users some way to toggle between latest release and "main"?
• URL considerations as mentioned above also need to get addressed

@AnneT and I talked about this task today, and we propose the following:

• When a new release tag is created, publish the docs for that release only to /codex/latest, not to /codex/v1.2.3
  • This will get the latest version published at /codex/latest in almost all scenarios. If it does break down (because someone pushes older tags or non-release tags to the repo, or because we publish a release outside the numerical order), it's easy to fix by pushing a dummy tag (and then deleting it), and we can restrict tag creation rights to make it less likely that strange things will happen
  • This stops publishing docs to /codex/v1.2.3, so we won't have an archive of older releases' docs. But we think that's fine, they're mostly just clutter, and the value of keeping them doesn't outweigh the confusion they can cause
• Make /codex a redirect to /codex/latest (right now it's a directory listing)
• Keep publishing the docs for the main branch to /codex/main, but add a banner on top explaining what it is and linking to /codex/latest
  • This banner should appear on every page, so it should be in the header or something
  • This can be implemented by checking for the absence of the CODEX_RELEASE environment variable, which is how we already implement hiding WIP components in the release docs but showing them in the main branch docs
• On Netlify deployment previews for individual Gerrit changes (URLs like 123456--wikimedia-codex.netlify.app), add a banner on top explaining what it is and linking to /codex/latest
  • This banner should be scarier/more urgent than the one on the main branch docs. It should probably be red. We don't want people using deployment previews except for the narrow purpose of testing a single patch.
  • This can be implemented by adding an environment variable in the branch-deploy NPM command, and then checking for that environment variable, similar to how the doc-release command sets the CODEX_RELEASE environment variable
• (Lower priority:) we already display the version number on the entry point page of the docs site, but we should find a place in the header or sidebar where we can display the version number so that it's visible on every page. This should also make it easier to check which version of the documentation someone's looking at

Rejected alternatives:

• We considered making /codex/latest a redirect to the latest version so that we could have both, but that doesn't work well because:
  • VitePress uses absolute URLs in its navigation links, so if someone visits /codex/latest but then clicks a link, they'd be taken to /codex/v1.2.3/something, and we don't necessarily want them to bookmark/share that URL.
  • We can't easily add a banner on docs for older versions saying they're outdated, because the docs are built at release time and then never changed. And when they're built, they are the latest version.
  • We could cirumvent these issues by building the docs twice for each release, once at /codex/v1.2.3 (with a warning banner) and once at /codex/latest (without the warning), but that doesn't seem worth it
• We considered putting a version switcher in the header, but we didn't want to encourage people to visit outdated or pre-release versions of the docs site. We want to aggressively steer people towards the latest release version, and reserve other versions only for people who have a specific reason why they need a different version. Those people will know where to find the version they need.

We have agreed on the proposal in Roan's comment above

Implementation notes:

The relevant code for how these doc sites are published is in the following places:

• The CI settings for Codex are here
  • The test event happens when a new version of a change is uploaded, and when that happens we execute the branchdeploy-codex-node16-npm-docker (in addition to the normal test job that runs npm test, which is inherited from the node16-browser-docker template)
  • The postmerge event happens when a change is merged to the main branch, and when that happens we execute the codex-docker-doc-publish job
  • The publish event happens when a new tag is created (i.e. when we push a release tag), and when that happens we execute the codex-docker-doc-tag-publish job
• The two -publish jobs are defined here
  • The -doc-publish job runs npm run doc, while the -doc-tag-publish job runs npm run doc-release
  • Both set the CODEX_DOC_ROOT environment variable, which is used in Codex's Vitepress config (here and here)
  • To set this variable, and to set docdst (which is the path where the documentation is published under https://doc.wikimedia.org/), the $DOC_PROJECT and $DOC_SUBPATH variables are used. The details of how those are computed are not important (the code is here), what matters is that for Codex $DOC_PROJECT is set to codex and DOC_SUBPATH is set to the branch or tag name (so main or v0.2.2)
• How the branchdeploy-codex-node16-npm-docker job is created is not important (the code is here and here); what matters is that it sets the BRANCHDEPLOY_AUTH_TOKEN and BRANCHDEPLOY_SITE_ID to the appropriate (secret) values and runs npm run branch-deploy
• These npm commands are all defined in the package.json file in the root of the Codex repo
  • npm run doc is simple: it runs npm run build in the docs package, after first building the other packages it depends on
  • npm run doc-release sets the CODEX_RELEASE environment variable to the version number extracted from the codex package's package.json, and then runs npm run doc
    • The value of this env var isn't currently used, and we could probably just set it to 1 instead. Only it's presence/absence is used, to include/exclude WIP components in the sidebar (here)
  • npm run branch-deploy runs npm run doc, also builds the sandbox, and then publishes everything to Netlify (note $ZUUL_CHANGE is the Gerrit change number)

With all that in mind, here's how we can implement the proposal:

In T311097#8365139, @Catrope wrote:

• When a new release tag is created, publish the docs for that release only to /codex/latest, not to /codex/v1.2.3

We can hardcode latest in the codex-docker-doc-tag-publish job, instead of using $DOC_SUBPATH. Note that changes to the integration-config repo need to be reviewed and deployed by someone from the RelEng team, and have to be tested in production. This particular change is low risk, but we won't be able to test it without deploying it and then pushing a tag to trigger it.

• Make /codex a redirect to /codex/latest (right now it's a directory listing)

This will require changes to the code in the integration-docroot repo. Relevant code is here and here. The easiest way might be to create the codex subdirectory in the org/wikimedia/doc directory, with an index.php file that does the redirect, hopefully as simple as $p = DocPage::newDirIndex( 'Codex' ); header( "Location: {$p->getUrlPath()}codex/" );, but I don't know this code super well.

• Keep publishing the docs for the main branch to /codex/main, but add a banner on top explaining what it is and linking to /codex/latest

As noted previously, this can be done by checking for the absence of the CODEX_RELEASE env var.

• On Netlify deployment previews for individual Gerrit changes (URLs like 123456--wikimedia-codex.netlify.app), add a banner on top explaining what it is and linking to /codex/latest

As noted previously, this can be done by adding an env var in the branch-deploy command, and then checking for that.

• (Lower priority:) we already display the version number on the entry point page of the docs site, but we should find a place in the header or sidebar where we can display the version number so that it's visible on every page. This should also make it easier to check which version of the documentation someone's looking at

This can be done by just importing the version from the codex package's package.json, like usage.md already does.

Change 859130 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[integration/docroot@master] [WIP] Add redirect from /codex to /codex/latest

https://gerrit.wikimedia.org/r/859130

Change 859141 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] docs: Add banners for main branch and deployment previews

https://gerrit.wikimedia.org/r/859141

Change 859530 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[integration/config@master] Codex: use `latest` instead of tag for releases

https://gerrit.wikimedia.org/r/859530

@bmartinezcalvo we could use some design review here! We've set up the following:

• On https://doc.wikimedia.org/codex/latest (which doesn't exist yet, but will be based on the latest release), you will not see a message
• On deployment previews (e.g. https://859141--wikimedia-codex.netlify.app/), we've added a warning message that alerts the user that they're looking at a deployment preview and directs them back to the official site (/codex/latest)
• On https://doc.wikimedia.org/codex/main/, you'll see a dismissable notice message that also links to the official site

Deployment branch message:

Main branch message:

Originally, I considered adding a full-width banner to the top of the page with this information, but since we have no design precedent for such a thing, and because the VitePress header styles are a bit gnarly, I decided to just use the CdxMessage component. This is similar to what appears on the docs for the old version of Vue, Vue 2.

Change 859596 had a related patch set uploaded (by Jforrester; author: Jforrester):

[integration/config@master] Zuul: [design/codex] Add codex-docker-doc-latest-publish

https://gerrit.wikimedia.org/r/859596

Change 859530 merged by jenkins-bot:

[integration/config@master] jjb: Provide codex-docker-doc-latest-publish

https://gerrit.wikimedia.org/r/859530

Change 859596 merged by jenkins-bot:

[integration/config@master] Zuul: [design/codex] Add codex-docker-doc-latest-publish

https://gerrit.wikimedia.org/r/859596

Change 859627 had a related patch set uploaded (by Catrope; author: Catrope):

[integration/docroot@master] doc: Link to the Codex docs for the latest release, not the main branch

https://gerrit.wikimedia.org/r/859627

Change 859141 merged by jenkins-bot:

[design/codex@main] docs: Add banners for main branch and deployment previews

https://gerrit.wikimedia.org/r/859141

Thanks @Jdforrester-WMF for tweaking and merging the integration-config patches! I re-pushed the v0.3.0 tag, and https://doc.wikimedia.org/codex/latest/ is now live.

I've also merged @AnneT's banners patch. The main branch banner is now live at https://doc.wikimedia.org/codex/main/ (and as before, the deployment preview banner can be seen at https://859141--wikimedia-codex.netlify.app/ ).

The integration-docroot patch to redirect /codex to /codex/latest ran into some trouble, and we may have to give up on that part. Relatedly, Antoine pointed out that the link to the Codex docs on the https://doc.wikimedia.org/ main page still points to /codex/main, so I've submitted https://gerrit.wikimedia.org/r/859627 to change that to /codex/latest.

The one pending issue is that James's tweaks to the integration-config patches causes the release documentation to still be published to https://doc.wikimedia.org/codex/v0.3.0 as well. If we want, we can add banners to those too. (We'd have to say something like "this version may be out of date, for the latest version see /latest", because the docs for old versions aren't rebuilt when a newer version is published.) We could do that by adding an env var or changing the name of the npm command name for the "tag" job vs the "latest" job.

Change 859627 merged by jenkins-bot:

[integration/docroot@master] doc: Link to the Codex docs for the latest release, not the main branch

https://gerrit.wikimedia.org/r/859627

Mentioned in SAL (#wikimedia-operations) [2022-11-23T15:28:48Z] <jforrester@deploy1002> Started deploy [integration/docroot@52e4a00]: Deploying 52e4a00 for T311097 pointing Codex docs to latest

Mentioned in SAL (#wikimedia-operations) [2022-11-23T15:29:03Z] <jforrester@deploy1002> Finished deploy [integration/docroot@52e4a00]: Deploying 52e4a00 for T311097 pointing Codex docs to latest (duration: 00m 14s)

In T311097#8413129, @AnneT wrote:

@bmartinezcalvo we could use some design review here! We've set up the following:

• On https://doc.wikimedia.org/codex/latest (which doesn't exist yet, but will be based on the latest release), you will not see a message
• On deployment previews (e.g. https://859141--wikimedia-codex.netlify.app/), we've added a warning message that alerts the user that they're looking at a deployment preview and directs them back to the official site (/codex/latest)
• On https://doc.wikimedia.org/codex/main/, you'll see a dismissable notice message that also links to the official site

Deployment branch message:

Main branch message:

Originally, I considered adding a full-width banner to the top of the page with this information, but since we have no design precedent for such a thing, and because the VitePress header styles are a bit gnarly, I decided to just use the CdxMessage component. This is similar to what appears on the docs for the old version of Vue, Vue 2.

As commented yesterday during our DST Engineering/Design sync I think these 2 links could be confusing for the users since they are too similar. So I propose the following in order to differentiate them more (apart from using the messages that you comment):

1. The first confusing thing is that https://doc.wikimedia.org/codex/main/ is not the main demo page. So I propose to use different names for the "Latest" and "Main". We could use for example:
   • https://doc.wikimedia.org/codex/latest > official
   • https://doc.wikimedia.org/codex/main/ > not-released
2. Apart from the name, I think we need to visually differentiate both demos so users clearly understand in which one they are. We could use white background for the latest (official) and a light gray for the main (not-released)

latest (official)	main (not-released)

Change 859130 abandoned by Anne Tomasevich:

[integration/docroot@master] [WIP] Add redirect from /codex to /codex/latest

Reason:

Not going to pursue this for now

https://gerrit.wikimedia.org/r/859130

Change 865151 had a related patch set uploaded (by Eric Gardner; author: Eric Gardner):

[mediawiki/core@master] Update Codex from v0.3.0 to v0.4.0

https://gerrit.wikimedia.org/r/865151

Change 865151 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.3.0 to v0.4.0

https://gerrit.wikimedia.org/r/865151

@bmartinez I like the idea of being clearer about the differentiation, but the background-color might be even further misleading to users that randomly come to the site (for example through a Phab link). I think the beta cluster does a visually horrible, but clearer job than a background color.

I also really like the idea of a different, eye-catching logo for the main and netlify builds!

As discussed elsewhere, we all agree that /main and /latest are far from ideal, but will postpone any more changes on the URLs until we decide what we're ultimately doing with the Codex docs site (e.g. potentially launching codex.wikimedia.org).

In T311097#8453147, @Volker_E wrote:

@bmartinez I like the idea of being clearer about the differentiation, but the background-color might be even further misleading to users that randomly come to the site (for example through a Phab link). I think the beta cluster does a visually horrible, but clearer job than a background color.

This is a great idea. It would be perfect for the user to have an obvious solution with a big tag like that one.

Moving this to Ready for Design because we need to figure out exactly what we want to do here.

If we have a big banner over the Codex "logo" (which is just text), we need to plan what it will say. It needs to clearly communicate what it means with few words.

One idea I had is to alias "main" to "beta." "Beta" is a commonly used term at Wikimedia, so people already know what it means. The main branch is really the same as what's on beta wikis - it represents what is currently merged, but not released. If we change the url to https://doc.wikimedia.org/codex/beta/, we can slap a big "Beta" label over the Codex logo and it will be very clear what it means.

In T311097#8467013, @AnneT wrote:

One idea I had is to alias "main" to "beta." "Beta" is a commonly used term at Wikimedia, so people already know what it means. The main branch is really the same as what's on beta wikis - it represents what is currently merged, but not released. If we change the url to https://doc.wikimedia.org/codex/beta/, we can slap a big "Beta" label over the Codex logo and it will be very clear what it means.

@AnneT totally agree, Beta would be perfect to explain what this Codex version is. I've mockup some designs with the Beta solution:

Op.1: using a green tag (as we have in beta cluster) and a gray notice message	Op.2: using a warning tag next to the logo and a warning message

For the message I would say:

You're viewing the docs for the beta version of Codex, which may contain features that have not been released yet. Codex users should visit the official docs.

Although the first option is a solution that we already use in beta cluster, we use the green color to communicate success actions so I wouldn't use green to represent a beta version of our system since it's not the last version. I think a warning tag and message is more accurate.

I agree with using the warning tag and message, and the message text updates. Thanks for mocking this up!

In T311097#8473903, @AnneT wrote:

I agree with using the warning tag and message, and the message text updates. Thanks for mocking this up!

@AnneT great, this is the Figma design in case you want to inspect the Beta tag. I've used the following styles to create it:

• Text 16/22px Bold
• background-color-warning-subtle
• border-color-warning

Regarding the codex/latest version. What if we rename it to codex/main or codex/official once the Beta name has been updated?

@AnneT @ldelench_wmf in February, we pulled this out of the sprint and into Refined/Up Next, but I'm not actually sure if we still want to do the remaining work to rename main to beta. We do point to latest now as the canonical version and the main site displays a warning box (not quite to @bmartinezcalvo's spec, but still useful). Wondering if we can backlog this for now, or if there are specific benefits of introducing the beta concept at this point.

In T311097#8794353, @CCiufo-WMF wrote:

@AnneT @ldelench_wmf in February, we pulled this out of the sprint and into Refined/Up Next, but I'm not actually sure if we still want to do the remaining work to rename main to beta. We do point to latest now as the canonical version and the main site displays a warning box (not quite to @bmartinezcalvo's spec, but still useful). Wondering if we can backlog this for now, or if there are specific benefits of introducing the beta concept at this point.

If we are going to rename the main version at some moment, I recommend doing it as soon as possible so users can be familiarized with the site name. If we use "main" for a long time, then when renaming to "beta" it will be more difficult to get used to the new name.

@bmartinezcalvo +1, if we want to do this we should do it now before the 1.0 release. I do think it would be a major improvement to switch from 'main' to 'beta'.