router
router copied to clipboard
apollographql
docs: display latest released version in doc content
In our documentation, we often refer to the latest version of things intentionally in code snippets and examples. Unfortunately, this causes the properties to drift over time.
We no longer control the mechanism for how the documentation gets rendered, so it seems like we'd need to take one of a couple approaches.
Approach 1
Let the documentation content stay static and use some sort of tokenization mechanism that interpolates a value from our documentation configuration (JSON) file into a location in the docs. So, for example, in a documentation page's markdown we'd have something like this:
Example markdown for this approach 1
This is the documentation talking about various things!
> Note: The latest version of the Router is ${{routerLatestVersion}}.
```bash
$ curl http://install/router/${{routerLatestVersion}}
```
```yaml
---
image: ghcr.io/apollographql/router:${{routerLatestVersion}}
```
... and then in the config.json file (a file that already exists), we'd have a — idk, straw-dog name — interpolatedVariables key and value pair object:
Example config.json
{
/* Other existing things */
"sidebar": { /* Existing stuff in the config.json */ },
"interpolatedVariables": {
"routerLatestVersion": "v1.0.0"
}
}
I don't think we make a close coupling between Cargo.toml and our documentation infrastructure in this case though, so we still have an xtask that sets the interpolatedVariables.routerLatestVersion at release time via the various xtask commands we have.
Approach 2
In this approach, the documentation remains with existing versions inline as static content in the markdown and we'd instead run a bit in our release xtasks that looks for some pattern in the documentation and we just replace it with the version we're releasing, again, extracted from Cargo.toml. The pattern in the markdown could be something like <!--router_version-->v1.0.0<!--router_version_end--> and we just always bump it via release xtask.
Example markdown for this approach 2
This is the documentation talking about various things!
> Note: The latest version of the Router is <!--router_version-->v1.0.0<!--router_version_end-->.
```bash
$ curl http://install/router/<!--router_version-->v1.0.0<!--router_version_end-->
```
```yaml
---
image: ghcr.io/apollographql/router:<!--router_version-->v1.0.0<!--router_version_end-->
```
Thoughts? Discuss?
If we wanted this sooner, Approach 2 is within the control of the team's tooling and assets. Approach 1 requires our documentation infrastructure to support it, and collaboration with that team. That said, it would probably benefit other (documented) projects, too.
Not on the docs team but... My preference is for Approach 1. The other approach still means committing every release.
Also, at the moment we have a weird situation where once we merge our docs go live right away. We need a URL for the docs that relate to currently unreleased code and a URL for the latest released version.
We should also bump the version in cargo.toml when the release happens to the next anticipated release version.
