From 7d3f48e09efa5e473d6624f28a996c839401202c Mon Sep 17 00:00:00 2001 From: James Zaki Date: Mon, 26 May 2025 19:18:46 +0100 Subject: [PATCH 1/7] Update docs readme --- docs/README.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index d8618ee29849..9d62b0bc0710 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,7 +24,7 @@ The .md files in the `docs/` directory are the docs. See the [Docusaurus website Aztec Docs are versioned. Every version known is literally a copy of the website, and is in `versioned_docs` (sidebars are in `versioned_sidebars`). Seems silly but it's not, it allows you to hot-fix previous versions. -When you look at the published docs site, you will see three versions in the version dropdown: `Next`, `alpha-testnet`, and the latest sandbox release e.g. `v0.86.0`. Updating the files in the `docs` folder will update the `Next` version, updating the files in `versioned_docs/version-alpha-testnet` folder will update the `alpha-testnet` version, and updating the files in the `versioned_docs/version-v0.86.0` folder will update the `versioned_docs/v0.86.0` version. Note that you cannot use the macros (`#include_aztec_version` and `#include_code`) in the `versioned_docs` folder, since those docs have already been processed and built. Instead, just drop the code snippets, version numbers or links directly in the docs as you'd like them to be rendered. +When you look at the published docs site, you will see three versions in the version dropdown: `Next`, `Latest`, and older versions e.g. `v0.86.0`. Updating the files in the `docs` folder will update the `Next` version, updating the files in `versioned_docs/version-latest` folder will update the `latest` version, and updating the files in the `versioned_docs/version-v0.86.0` folder will update the `versioned_docs/v0.86.0` version. Note that you cannot use the macros (`#include_aztec_version` and `#include_code`) in the `versioned_docs` folder, since those docs have already been processed and built. Instead, just drop the code snippets, version numbers or links directly in the docs as you'd like them to be rendered. The way docs builds work is the following: @@ -40,6 +40,32 @@ COMMIT_TAG=v0.84.0 yarn build You can add the aztec version to a docs page without the `v` prefix with `#include_version_without_prefix`, so COMMIT_TAG `v0.85.0` will render as `0.85.0`. +## Adding A Version + +Versions of docs can be created automatically via a github action, or manually. + +From earlier, the release github workflow is triggered on pushes to `master` or `next` branches and does two things: +1. using google's `Release-Please` action to create a new PR and version tag +2. creates a build artifact for the new version of the docs (a folder in `versioned_docs`) + +To manually perform step two locally: +- Checkout the branch/tag of the version of docs you'd like to create +- From the desired branch/tag, perform the "cut version" step of the github action ([Release-Please.yml](https://github.com/AztecProtocol/aztec-packages/blob/next/.github%2Fworkflows%2Frelease-please.yml#L72-L78)). Note: you will have to set COMMIT_TAG to "v0.xx.x" or "vlatest" +- Then the newly created version of docs under `docs/versioned_docs` can be stashed, to later pop on your branch that you want to commit the new versioned docs to. + +### A special note about branches + +Adding docs: Only the `next` branch will have protocol changes, whereas `master` will not. So any documentation refering to these new protocol changes should only be applied to `next`. All other docs updates should be applied to `master`. + +Generating docs: Since `master` does not contain the changes of the next protocol update, then generating a document version from `master` will not correctly show what the docs version `next` is supposed to contain. For this reason, doc releases should come from `next`. + +:::info Summary +- The only place to refer to the latest protocol changes is in the `next` branch under `docs/docs`, shown as the `next` docs version +- All other docs updates should go to `master` (auto applied to `next`), and when releases are made this will be the `latest` docs tag +- When a new release is made, the current `latest` version of the docs must be recreated at it's specific version number, and the previous `latest` folder (in `versioned_docs`) be removed to make way for the actual latest + +::; + ### How do I change the versions that show in the website When docusaurus builds, it looks for the `versions.json` file, and builds the versions in there, together with the version in `docs`. From 3cea1ff2e1d6735aced7effca47d0924b2712ac3 Mon Sep 17 00:00:00 2001 From: James Zaki Date: Mon, 26 May 2025 19:22:04 +0100 Subject: [PATCH 2/7] Update docs readme --- docs/README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index 9d62b0bc0710..5fa0e1e77c6d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,6 +40,10 @@ COMMIT_TAG=v0.84.0 yarn build You can add the aztec version to a docs page without the `v` prefix with `#include_version_without_prefix`, so COMMIT_TAG `v0.85.0` will render as `0.85.0`. +### How do I change the versions that show in the website + +When docusaurus builds, it looks for the `versions.json` file, and builds the versions in there, together with the version in `docs`. + ## Adding A Version Versions of docs can be created automatically via a github action, or manually. @@ -59,16 +63,11 @@ Adding docs: Only the `next` branch will have protocol changes, whereas `master` Generating docs: Since `master` does not contain the changes of the next protocol update, then generating a document version from `master` will not correctly show what the docs version `next` is supposed to contain. For this reason, doc releases should come from `next`. -:::info Summary +### Summary - The only place to refer to the latest protocol changes is in the `next` branch under `docs/docs`, shown as the `next` docs version - All other docs updates should go to `master` (auto applied to `next`), and when releases are made this will be the `latest` docs tag - When a new release is made, the current `latest` version of the docs must be recreated at it's specific version number, and the previous `latest` folder (in `versioned_docs`) be removed to make way for the actual latest -::; - -### How do I change the versions that show in the website - -When docusaurus builds, it looks for the `versions.json` file, and builds the versions in there, together with the version in `docs`. ## Releases From 249e4e4b001e1c61d904966f61494aa2b5cada59 Mon Sep 17 00:00:00 2001 From: James Zaki Date: Tue, 27 May 2025 09:21:54 +0100 Subject: [PATCH 3/7] Add handling of Latest docs label --- docs/README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 5fa0e1e77c6d..c95e6ffdc0b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -26,19 +26,21 @@ Aztec Docs are versioned. Every version known is literally a copy of the website When you look at the published docs site, you will see three versions in the version dropdown: `Next`, `Latest`, and older versions e.g. `v0.86.0`. Updating the files in the `docs` folder will update the `Next` version, updating the files in `versioned_docs/version-latest` folder will update the `latest` version, and updating the files in the `versioned_docs/version-v0.86.0` folder will update the `versioned_docs/v0.86.0` version. Note that you cannot use the macros (`#include_aztec_version` and `#include_code`) in the `versioned_docs` folder, since those docs have already been processed and built. Instead, just drop the code snippets, version numbers or links directly in the docs as you'd like them to be rendered. +Note: `Latest` version dropdown is a special case since it will initially be created as any other version (eg `v0.87.2`), but the directory and label will need to be renamed to display as `Latest` by docusaurus. + The way docs builds work is the following: - CI runs on merge to master, builds the dependencies needed to build the docs, then deploys on the main docs website - [This Github Action](../.github/workflows/docs-preview.yml) runs on pull requests if they have any docs change, and quite similarly builds the dependencies and the docs, then gives you a nice preview so you can check that everything is alright - [This Github Action](../.github/workflows/release-please.yml) is Release-Please, a framework made to organize different commits into releases. When it merges to master, it runs. When it runs, it builds the dependencies and cuts a new version of the docs, with the same tag that is being released -The `#include_aztec_version` and `#include_code` macros look for the version tag in an environment variable `COMMIT_TAG`, so you can build the docs specifying a version with the following command (e.g. for v0.84.0). Remove the versions listed in `versions.json` before running: +The `#include_aztec_version` and `#include_code` macros look for the version tag in an environment variable `COMMIT_TAG`, so you can build the docs specifying a version with the following command (e.g. for v0.86.0). Remove the versions listed in `versions.json` before running: ```bash -COMMIT_TAG=v0.84.0 yarn build +COMMIT_TAG=v0.86.0 yarn build ``` -You can add the aztec version to a docs page without the `v` prefix with `#include_version_without_prefix`, so COMMIT_TAG `v0.85.0` will render as `0.85.0`. +You can add the aztec version to a docs page without the `v` prefix with `#include_version_without_prefix`, so COMMIT_TAG `v0.86.0` will render as `0.86.0`. ### How do I change the versions that show in the website @@ -54,8 +56,13 @@ From earlier, the release github workflow is triggered on pushes to `master` or To manually perform step two locally: - Checkout the branch/tag of the version of docs you'd like to create -- From the desired branch/tag, perform the "cut version" step of the github action ([Release-Please.yml](https://github.com/AztecProtocol/aztec-packages/blob/next/.github%2Fworkflows%2Frelease-please.yml#L72-L78)). Note: you will have to set COMMIT_TAG to "v0.xx.x" or "vlatest" +- From the desired branch/tag, perform the "cut version" step of the github action ([Release-Please.yml](https://github.com/AztecProtocol/aztec-packages/blob/next/.github%2Fworkflows%2Frelease-please.yml#L72-L78)). Note: you will have to set COMMIT_TAG to "v0.xx.x" - Then the newly created version of docs under `docs/versioned_docs` can be stashed, to later pop on your branch that you want to commit the new versioned docs to. +- Since the new version is likely taking the place of latest: + - Go to `versioned_docs` and rename `version-latest` to it's version (eg `version-v0.xx.x`) + - Rename the newly created version as `version-latest` +- If desired, delete any past versions we no longer want to display +- Update `versions.json` ### A special note about branches From 08bce6b1c06d8b903afcbe6d3554278cc761c864 Mon Sep 17 00:00:00 2001 From: James Zaki Date: Tue, 27 May 2025 15:15:09 +0100 Subject: [PATCH 4/7] doc release process --- docs/README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index c95e6ffdc0b2..f6eeea7895e2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -68,7 +68,12 @@ To manually perform step two locally: Adding docs: Only the `next` branch will have protocol changes, whereas `master` will not. So any documentation refering to these new protocol changes should only be applied to `next`. All other docs updates should be applied to `master`. -Generating docs: Since `master` does not contain the changes of the next protocol update, then generating a document version from `master` will not correctly show what the docs version `next` is supposed to contain. For this reason, doc releases should come from `next`. +Generating docs: +- Most of the time we want the label `Next` to contain upcoming changes, excluding documentation of upcoming protocol changes. For this we release docs straight from `master`. +- Before a protocol release, we want the docs label `Next` to contain upcoming changes AND documentation of upcoming protocol changes, then: + 1. Apply protocol docs to `next` branch in `docs/docs` (we can do this with an ongoing protocol docs branch, periodically merging into `next`) + 2. cherrypick these commits (or patch/rebase the protocol docs branch) into `master` to apply to `docs/docs` + 3. releasing from `master` now will show the `Next` label to have all upcoming changes including the protocol changes ### Summary - The only place to refer to the latest protocol changes is in the `next` branch under `docs/docs`, shown as the `next` docs version From bb480fe72f019dce2b5adba3fb75e42acafd8779 Mon Sep 17 00:00:00 2001 From: James Zaki Date: Tue, 27 May 2025 16:41:21 +0100 Subject: [PATCH 5/7] docs: emphasise commits to master --- docs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index f6eeea7895e2..d35d741a95fd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,7 +66,9 @@ To manually perform step two locally: ### A special note about branches -Adding docs: Only the `next` branch will have protocol changes, whereas `master` will not. So any documentation refering to these new protocol changes should only be applied to `next`. All other docs updates should be applied to `master`. +Adding docs: +- All docs changes, especially changes to `versioned_docs`, should only go to the `master` branch +- Exceptionally when documenting new protocol changes, these should go to the `next` branch, within `docs/docs` Generating docs: - Most of the time we want the label `Next` to contain upcoming changes, excluding documentation of upcoming protocol changes. For this we release docs straight from `master`. From 5741acd9d7ea15dafa1cbd714e591f072157d31c Mon Sep 17 00:00:00 2001 From: James Zaki Date: Wed, 28 May 2025 13:22:18 +0100 Subject: [PATCH 6/7] Rephrase exception as future option from pr review --- docs/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index d35d741a95fd..3795441a5b21 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,11 +66,12 @@ To manually perform step two locally: ### A special note about branches -Adding docs: +**Adding docs** - All docs changes, especially changes to `versioned_docs`, should only go to the `master` branch -- Exceptionally when documenting new protocol changes, these should go to the `next` branch, within `docs/docs` -Generating docs: +That means, docs can only refer to a proposed protocol change once its release tag is on `master`. Unless otherwise patched/cherry-picked from other commits and applied to its own versioned docs label. + +**Generating docs** - Most of the time we want the label `Next` to contain upcoming changes, excluding documentation of upcoming protocol changes. For this we release docs straight from `master`. - Before a protocol release, we want the docs label `Next` to contain upcoming changes AND documentation of upcoming protocol changes, then: 1. Apply protocol docs to `next` branch in `docs/docs` (we can do this with an ongoing protocol docs branch, periodically merging into `next`) From da00f45d794675255162f1760578962f28491914 Mon Sep 17 00:00:00 2001 From: James Zaki Date: Thu, 29 May 2025 19:36:23 +0100 Subject: [PATCH 7/7] add detail about docusaurus versioning --- docs/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/README.md b/docs/README.md index 3795441a5b21..ae369df600bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -64,6 +64,8 @@ To manually perform step two locally: - If desired, delete any past versions we no longer want to display - Update `versions.json` +For more details, see [Docusaurus Versioning](https://docusaurus.io/docs/versioning#configuring-versioning-behavior) + ### A special note about branches **Adding docs** @@ -73,6 +75,7 @@ That means, docs can only refer to a proposed protocol change once its release t **Generating docs** - Most of the time we want the label `Next` to contain upcoming changes, excluding documentation of upcoming protocol changes. For this we release docs straight from `master`. + - This can be removed by setting `includeCurrentVersion: false` in `docs/docusaurus.config.js` - Before a protocol release, we want the docs label `Next` to contain upcoming changes AND documentation of upcoming protocol changes, then: 1. Apply protocol docs to `next` branch in `docs/docs` (we can do this with an ongoing protocol docs branch, periodically merging into `next`) 2. cherrypick these commits (or patch/rebase the protocol docs branch) into `master` to apply to `docs/docs`