Page MenuHomePhabricator

docs: Consider making the latest release branch the default for the live docs site
Open, In Progress, HighPublic3 Estimated Story Points

Description

We have been linking to https://doc.wikimedia.org/codex/main/ as the canonical version of the docs site, which displays the docs site as generated by the current main branch. However, this has already led to multiple instances of confusion where a developer was trying to implement a component in MediaWiki, which contains the latest release of Codex, but reading the usage docs on the live site, which reflects a version that hadn't been released yet.

We already get an instance of the site for each release (see the different versions here). We should consider:

  1. Whether we should refer to the latest release's instance as the canonical version, to be shared widely
  2. If so, consider changing our Netlify setup to base the canonical version on the latest release, instead of forcing users to go to a new link every time a new release is cut
  3. Consider displaying a banner on non-canonical versions of the site (old releases, main branch, patch instances) to inform the user that they are not on the canonical version

Event Timeline

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
ldelench_wmf set the point value for this task to 3.Sep 19 2022, 3:34 PM

@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:

  • 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.

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

AnneT changed the task status from Open to In Progress.Mon, Nov 21, 10:01 PM

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

I've got a WIP branch up for the docs site banners, which will have to wait to be merged until /codex/latest actually exists. Assigning to @Catrope to continue looking into the changes on the doc.wikimedia.org side

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:

Deployment branch message:

image.png (572×1 px, 61 KB)

Main branch message:

image.png (638×1 px, 75 KB)

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)

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

Deployment branch message:

image.png (572×1 px, 61 KB)

Main branch message:

image.png (638×1 px, 75 KB)

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:
  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.png (1×2 px, 292 KB)
Main.png (1×2 px, 300 KB)
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