fix(docs): Show latest released code on published site

[spalladino]

Our docs build script checks a INCLUDE_RELEASED_CODE env var to determine what code snippets to include in the site build (either latest released version or master). This should be set when deploying the site to the public, which happens on every build on master. So we need to set this env var when on master.

However, just setting the env var doesn't work, since we need to get it inside the docs docker build context. Also, we need this build to be seen as different than a build in a branch by the check_rebuild script, even if they have the same content hash, since INCLUDE_RELEASED_CODE affects the result.

One option for fixing this would've been adding a mechanism for passing args to the build script in build-system which in turn passes them as ARGs to the docker build call, so they can be turned into ENV vars visible by our scripts. Another option could've been defining a different Dockerfile, a Dockerfile.master, where this ENV var is hardcoded. However, neither of these solves the check_rebuild issue.

So what we're doing is manually changing the contents of the docs folder by writing a .env file with the env var we need to set, and loading it when building. This both gets the env var inside the docker context (since we're passing it in a file) and triggers a rebuild when needed (since it changes the inputs used for calculating the content hash).

Separately from the issues above, we need to manually fetch additional commits from the repo, since we need to load code from the released commit. We're doing that in the same step where we set up the .env, which is after the checkout but before the build step.

While this approach seems to work, it is doing much stuff around build-system, rather than playing along with it. So @charlielye I'd appreciate your comments here before merging!

[charlielye]

Don't fully understand the situation yet.
Ideally we would:

• at end of master run, in deploy job, publish docs to something like docs.aztec.network/master
• at end of tagged run, in deploy job, publish docs to something like docs.aztec.network/v1.2.3
• make docs.aztec.network redirect to latest version number

There shouldn't be any need for our docs to be treated as any special case here, unless im missing something.

[charlielye]

It doesn't seem like this PR does anything wildly disturbing however, so happy to approve if it quickly solves something.

(edit: hmm, maybe it does have some weird implications. as it changes the content-hash no other parts of the build will ever be able to find it. be that downstream jobs (ok there are none), or scripts like bootstrap_docker that attempt to download images based on content-hash (probably doesn't matter for docs).

It is a hack though.

[spalladino]

Ideally we would:

at end of master run, in deploy job, publish docs to something like docs.aztec.network/master
at end of tagged run, in deploy job, publish docs to something like docs.aztec.network/v1.2.3
make docs.aztec.network redirect to latest version number

We don't have versioned docs for Aztec, so every deployment goes to a single site. The rationale for treating our docs specially is that docs for a given release are very often changed after that version has been released, as devrel writes new content for that version or document issues and workarounds. This lets them put content online fast, without having to wait for the next release cycle.

However, snippets need to be sourced from the latest release, since users usually copy-paste them directly, and they must be compatible with the released version they are working with.

[charlielye]

If docs need to be able to do releases "after the fact", it can either be done manually, or via a specific docs deployment workflow in our config.yml.

I suspect we also should also start versioning our docs.

[spalladino]

If docs need to be able to do releases "after the fact", it can either be done manually, or via a specific docs deployment workflow in our config.yml.

@critesjosh @signorecello @catmcgee can you chime in here? Main question is whether docs changes should be held off until the next release (with the option to trigger a deployment manually if needed) and be published along with the new version of the packages, or should be published immediately as they are merged into master.

[charlielye]

Is it so hard to version them? Then we can have both master and tagged versions.
Perhaps this is a separate discussion, but as per a call I was just on, it's going to be expected to have "major version bumps with breaking changes", and it seems wrong to take the docs for previous versions away.

I guess versioning doesn't directly solve the other question of "are docs, like code, immutable". i.e. once released, we're stuck with them until another release. Master would always point to the latest.

It doesn't sound like this is a great workflow as it seems we are accepting that docs can be "lagging behind" the releases in terms of them needing updates etc, which seems reasonable. I'm not sure if we can live in world where we say the docs are fixed and immutable to the version they were released on, but if you want the very latest version of the docs, you look at the "master" docs. If this was acceptable, this would be the best approach. We just version the docs and that's that.

However if that's not good enough, we could have the option to update the docs for already released versions via a CCI workflow that can be manually triggered.

[spalladino]

To clarify, when you say "version the docs", you mean...?

• Docs for v1.2.3 are the ones on the repo when we tag v1.2.3, and get uploaded to a v1.2.3 path in the site
• Docs for v1.2.3 live in a v1.2.3 folder in the repo, which we make visible to the public when we tag v1.2.3

[critesjosh]

Updating the docs with every push to master is a fine workflow for the stage of development we are at. We always want people using the latest version, there hasn't been a need for referencing old docs versions afaik.

We haven't had any major docs updates staged for a release (maybe once). Since it's infrequent, we can just stage updates in a draft PR for now to keep it simple. We can revisit the process when supporting previous releases is more important.

[charlielye]

To clarify, when you say "version the docs", you mean...?

• Docs for v1.2.3 are the ones on the repo when we tag v1.2.3, and get uploaded to a v1.2.3 path in the site
• Docs for v1.2.3 live in a v1.2.3 folder in the repo, which we make visible to the public when we tag v1.2.3

I meant the first one. But, assuming this is just getting ahead of ourselves, then let's just focus on the master version, which is what this was originally all about.

I don't understand why we need this approach. Why does INCLUDE_RELEASED_CODE exist?

Our docs build script checks a INCLUDE_RELEASED_CODE env var to determine what code snippets to include in the site build (either latest released version or master).

Why are the docs not just built off of whatever has been created through the pipeline, and released at the end of the pipeline along with our other stuff? (we do releases on master now, at least for dockerhub stuff, would like to extend this to npm under a master dist tag.)

[spalladino]

Why does INCLUDE_RELEASED_CODE exist? Why are the docs not just built off of whatever has been created through the pipeline, and released at the end of the pipeline along with our other stuff?

The pipeline on master has unreleased code. If we deploy our docs showing snippets from unreleased code, our users will try to copy them and fail. This happened so often that led us to include this toggle. The "weird" thing here is that we want the text to be the latest on master, as @critesjosh mentions above, but show code snippets that reference the latest release.

However, if your question was hinting at "why don't we always build docs with the latest released code snippets" (ie INCLUDE_RELEASED_CODE is always set), it's a fair point. The idea was to build PRs with the latest version of everything, so you would know the website would look like if there was a release; but we're not doing deploy previews anymore, so maybe it's not worth it.

[signorecello]

Hey as you know I've been working a lot with Noir docs, which are even more problematic given the versioning. In this case, we want two things:

Tagged version

We want a version of the docs that matches the released version. So given a timeline such as:

1. Version 0.16.0 is on <--- Docs are here
2. Engineers make breaking changes <---- Docs aren't here yet because the 0.17.0 tag isn't here yet
3. Version 0.17.0 is released <--- Docs are here

Current version

We want a version of the docs that reflects everything that is in master. So the timeline:

1. Version 0.16.0 is on <---- Docs are here
2. Engineers make breaking changes <---- Docs are here because they don't care about tags

Without knowing the specifics of how docs are built here, this could be made with docusaurus versions. Wait wait wait, don't freak out yet, let me finish 😄

My theoretical approach would be:

• There is only a version of the docs in the codebase: master
• The release workflow tags a new version (with release-please I believe)
• Release PR is merged, triggers the workflow_dispatch action
• workflow_dispatch cuts a new version for the tagged release and deploys it
• Codebase still only has the docs in "master"

This has the disadvantage of making it kind of impossible to change docs in previous versions made in the past. For example if we're in 0.16.0 and there's a typo, we can't fix it until a new release comes in. This is unacceptable for Noir, but I believe would be an acceptable tradeoff here

[signorecello]

So a quick chat after, seems like this fix just makes it work fine for the time being 👍 I wouldn't fix if it ain't broken!

[spalladino]

To keep everyone reading this up to date, we just discussed @signorecello's suggestion over the phone together with @critesjosh. We concluded that a versioned approach would be useful in the future, when there's demand to keep docs for older versions available. However, right now we are pushing our users to stay on the latest release of the sandbox, and it's more common for devrel to make improvement and changes to existing docs than it is to document breaking changes, hence the workflow of "always publish texts for master but with the code from the latest release" works fine.