Change Details

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 ([[ https://doc.wikimedia.org/codex/ | 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

== Background goal 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 ([[ https://doc.wikimedia.org/codex/ | 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 === Design solution | {F35870123} | {F35870131} | | **Op.1**: using a green tag (as we have in [[ https://en.wikipedia.beta.wmflabs.org/wiki/Main_Page?useskin=vector-2022 | beta cluster ]]) and a gray notice message | **Op.2**: using a warning tag next to the logo and a warning message | New message proposal: > 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. NOTE: 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**. === Acceptance criteria (or done) **Main/Beta version:** [] Update link from codex/main to codex/beta (https://doc.wikimedia.org/codex/beta/) [] Add tag next to the Codex logo to indicate that this is the beta version [] Use a warning message with this text: //"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."// **Latest version** [] Update link name //(if needed)//

== Background goal 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 ([[ https://doc.wikimedia.org/codex/ | 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 === Design solution | {F35870123} | {F35870131} | | **Op.1**: using a green tag (as we have in [[ https://en.wikipedia.beta.wmflabs.org/wiki/Main_Page?useskin=vector-2022 | beta cluster ]]) and a gray notice message | **Op.2**: using a warning tag next to the logo and a warning message | New message proposal: > 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. NOTE: 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**. === Acceptance criteria (or done) **Main/Beta version:** [] Update link from codex/main to codex/beta (https://doc.wikimedia.org/codex/beta/) [] Add tag next to the Codex logo to indicate that this is the beta version [] Use a warning message with this text: //"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."// **Latest version** [] Update link name //(if needed)//