diff --git a/README.md b/README.md index 281df1899..94fdebc59 100644 --- a/README.md +++ b/README.md @@ -40,114 +40,254 @@ You can launch a remote Development Environment with [Okteto](https://okteto.com *A new version of the docs is created once the documentation for a certain version is "finished". This is typically done in preparation of a new release.* -### Update Variables - -Before creating a new version, make sure the variables are up to date so that they are included in the released version: - -Review the content of `src/content/variables.json` and update the values of `cliVersion` and `chartVersion`. \ -If the release comes with a new or a removed Kubernetes version, update `kubernetesMinVersion` and `kubernetesMaxVersion` accordingly. \ -Finally, update the value of `syncthingVersion` with the version specified [here](https://github.com/okteto/okteto/blob/master/Dockerfile#L8). +This process will: +- Release version X.Y as the new official version (e.g., 1.41) +- Move the previous official version to archived versions (e.g., 1.40 → archived) +- Set up version X.(Y+1) as the next unreleased version (e.g., 1.42) +- Remove the oldest version to maintain 12 total versions + +**Prerequisites:** +- Determine the version number for the new release (e.g., `1.41`) +- Have release notes ready for the new version in `src/content/release-notes.mdx` + +### Step 1: Update Variables for the New Release + +Update `src/content/variables.json` with values for the version being released: + +1. Update `cliVersion` to the new Okteto CLI version (e.g., `3.16.0`) +2. Update `chartVersion` to match the new release version (e.g., `1.41.0`) +3. Update `syncthingVersion` from [this Dockerfile line](https://github.com/okteto/okteto/blob/master/Dockerfile#L9) +4. If Kubernetes version support changed, update `kubernetesMinVersion` and `kubernetesMaxVersion` + +Example: +```json +{ + "kubernetesMinVersion": "1.32", + "kubernetesMaxVersion": "1.34", + "cliVersion": "3.16.0", + "chartVersion": "1.41.0", + "syncthingVersion": "2.0.14" +} +``` +### Step 2: Create the New Version -### Create a new version -To create a new version, run the following commands: +Run the docusaurus version command with the new version number: -``` +```bash yarn run docusaurus docs:version 1.XX ``` -This will create a new version with the docs on your current branch. +Replace `1.XX` with your version number (e.g., `1.41`). + +This command will: +- Create `versioned_docs/version-1.XX/` with a snapshot of current docs +- Create `versioned_sidebars/version-1.XX-sidebars.json` with the sidebar config +- Add `1.XX` to the top of `versions.json` + +### Step 3: Update docusaurus.config.js + +Modify the `presets.docs.versions` section of [`docusaurus.config.js`](docusaurus.config.js): + +1. **Update `lastVersion`** to the new release version (e.g., `1.41`) + +2. **Update `current`** label and path to the NEXT unreleased version: + ```js + current: { + label: '1.42', // NEW_VERSION + 1 + path: '1.42', + } + ``` + +3. **Add new release version entry** at the top of `versions` object: + ```js + '1.41': { + label: '1.41', + path: '/', + banner: 'none', + }, + ``` + +4. **Update previous official version** (change path from `/` to version number and banner to `unmaintained`): + ```js + '1.40': { + label: '1.40', + path: '1.40', // changed from '/' + banner: 'unmaintained', // changed from 'none' + }, + ``` + +5. **Remove the oldest version entry** from the `versions` object (to maintain 12 versions total) + +### Step 4: Update netlify.toml Redirects + +Update the redirect rules at the bottom of [`netlify.toml`](netlify.toml): + +1. **Update official version redirect:** + ```toml + [[redirects]] + from = "/docs/1.41/*" # NEW_VERSION + to = "/docs/:splat" + status = 301 + ``` + +2. **Update unreleased version redirect:** + ```toml + [[redirects]] + from = "/docs/unreleased/*" + to = "/docs/1.42/:splat" # NEW_VERSION + 1 + status = 302 + ``` + +3. **Add redirect for the oldest removed version:** + ```toml + [[redirects]] + from = "/docs/1.29/*" # OLDEST_VERSION being removed + to = "/docs/:splat" + status = 302 + ``` + +### Step 5: Update archives.md + +Update [`src/pages/archives.md`](src/pages/archives.md): + +1. **Update "Current released version" table** with the new version: + ```markdown + | Version | Documentation | Release Notes | + | :------ | :----------------: | -------------------------------: | + | 1.41 | [Documentation](/) | [Release Notes](/release-notes/) | + ``` + +2. **Add previous official version** to the "Previously released versions" table: + ```markdown + | 1.40 | [Documentation](/1.40) | [Release Notes](/1.40/release-notes/) | + ``` + +3. **Remove the oldest version** from the "Previously released versions" table + +### Step 6: Remove the Oldest Version Files + +Identify the oldest version from `versions.json` (should be at the bottom) and remove its files: + +```bash +# Example: removing version 1.29 +rm -rf versioned_docs/version-1.29 +rm -rf versioned_sidebars/version-1.29-sidebars.json +``` -### Change the default version +**Manually remove the oldest version** from [`versions.json`](versions.json) (remove from the bottom of the array). -*The default version of the docs is created and published once a new version of Okteto is available. This is typically done as part of the release process of Okteto Self-Hosted.* +### Step 7: Archive Old Release Notes +Move the oldest version's release notes from active to archived: -Modify the `presets.docs.versions` section of [`docusaurus.config.js`](docusaurus.config.js) as follows: +1. **Cut the oldest version section** from the bottom of [`src/content/release-notes.mdx`](src/content/release-notes.mdx) +2. **Paste it at the top** of [`src/content/archived-release-notes.mdx`](src/content/archived-release-notes.mdx) (after the intro paragraph, before other versions) +### Step 8: Verify the Build -1. Update `lastVersion` to the new _official_ version +Run the build to catch any broken links or anchors: -2. Update `current` to _unreleased_ version in development +```bash +yarn build +``` -3. Update the values of the `path` of the previous official version in the `versions` subsection to match the version number. +Fix any errors before proceeding. Common issues: +- Broken anchor links from moved release notes +- Missing redirects +- Invalid configuration in docusaurus.config.js - Before - ``` - "1.4": { - label: "1.4", - path: "/", - banner: "none", - }, - ``` +### Step 9: Commit and Create Pull Request - After - ``` - "1.4": { - label: "1.4", - path: "1.4", - banner: "unmaintained", - }, - ``` +```bash +git add . +git commit -m "Release version 1.XX documentation" +git push +``` -4. Add a new entry in the `versions` subsection to match the new _official_ version, with `/` as the path. - - ``` - "1.5": { - label: "1.5", - path: "/", - banner: "none", - }, - ``` +Create a pull request and reference a recent version release PR as an example (check recent merged PRs with titles like "Release version X.XX documentation"). + + +## Quick Reference for Automation + +For agents or scripts automating this process, here are the key parameters: + +**Given:** +- `NEW_VERSION` = version being released (e.g., `1.41`) +- `PREV_VERSION` = current official version that will be archived (from `lastVersion` in docusaurus.config.js, e.g., `1.40`) +- `NEXT_VERSION` = NEW_VERSION + 1 (e.g., `1.42`) +- `OLDEST_VERSION` = last version in `versions.json` array (e.g., `1.29`) + +**Files to modify:** + +1. **src/content/variables.json** - Update with new release values +2. **Run command:** `yarn run docusaurus docs:version {NEW_VERSION}` +3. **docusaurus.config.js:** + - `lastVersion: '{NEW_VERSION}'` + - `current.label: '{NEXT_VERSION}'` + - `current.path: '{NEXT_VERSION}'` + - Add `'{NEW_VERSION}': { label: '{NEW_VERSION}', path: '/', banner: 'none' }` at top of versions + - Change `'{PREV_VERSION}'` path from `'/'` to `'{PREV_VERSION}'` and banner from `'none'` to `'unmaintained'` + - Remove `'{OLDEST_VERSION}'` entry from versions +4. **netlify.toml:** + - Official redirect: `from = "/docs/{NEW_VERSION}/*"` + - Unreleased redirect: `to = "/docs/{NEXT_VERSION}/:splat"` + - Add deprecated redirect: `from = "/docs/{OLDEST_VERSION}/*"` +5. **src/pages/archives.md:** + - Update current version table to `{NEW_VERSION}` + - Add `{PREV_VERSION}` to previous versions table + - Remove `{OLDEST_VERSION}` from previous versions table +6. **Delete files:** `versioned_docs/version-{OLDEST_VERSION}/` and `versioned_sidebars/version-{OLDEST_VERSION}-sidebars.json` +7. **versions.json** - Remove `{OLDEST_VERSION}` from array (should be last item) +8. **src/content/release-notes.mdx** - Cut bottom section for `{OLDEST_VERSION}` +9. **src/content/archived-release-notes.mdx** - Paste `{OLDEST_VERSION}` section at top (after intro) +10. **Run:** `yarn build` to verify + +**Version count:** Maintain exactly 12 versions in `versions.json` after completion. -Modify the redirection rules on `netlify.toml` so that `/docs//` redirects to `/docs` and `/docs/unreleased/` redirects to `/docs/`. +### After the new version has been merged, request a new search index and update variables for the unreleased docs version -``` -# Redirect official version to docs root -[[redirects]] - from = "/docs/1.5/*" - to = "/docs/:splat" - status = 301 - -# Redirect unreleased to "current" version -[[redirects]] - from = "/docs/unreleased/*" - to = "/docs/1.6/:splat" - status = 302 -``` +Once the new version is live in production, complete these post-release tasks: -Update `/src/pages/archives.md` with the new "current" version and the table of "previous" versions to remove the oldest one. +#### Update Search Index -Remove the oldest version by following these steps: +Request a new search index from Algolia (manual step - requires login): -- Remove the files for the oldest version from the folders `versioned_docs` and `versioned_sidebars`. -- Remove the oldest version from the file `versions.json`. -- Modify the `presets.docs.versions` section of [`docusaurus.config.js`](docusaurus.config.js) to remove the entry in the `versions` subsection for the oldest version to only keep 6 versions. -- Move the release notes from the oldest version from the bottom of the [Release Notes page](src/content/release-notes.mdx) to the top of the [Archived Release Notes page](src/content/archived-release-notes.mdx). -- Run `yarn build` to catch any broken anchors resulting from the previous step. -- Add a redirect in the file `netlify.toml` from the oldest version to the default version: +1. Log in to [Algolia Crawler](https://crawler.algolia.com/admin/crawlers) +2. On the crawlers' page, select "Okteto" +3. Click on "Restart crawling" -``` -# Redirect official version to docs root -[[redirects]] - from = "/docs/1.5/*" - to = "/docs/:splat" - status = 301 -``` +The search index will be completed in a few minutes. -https://github.com/okteto/docs/pull/1122 is a good example of how to set up the files for version 1.38 +#### Update Variables for Next Unreleased Version +Update `src/content/variables.json` to prepare for the next development cycle: -### After the new version has been merged, request a new search index and update variables for the unreleased docs version -Once the new version is live in production, you need to request a new search index to Algolia. +1. Increment `cliVersion` to the expected next CLI version +2. Increment `chartVersion` to match `{NEXT_VERSION}.0` +3. Keep other values unless there are known changes -1. Log in [Algolia](https://crawler.algolia.com/admin/crawlers) -2. On the crawlers’ page, select "Okteto" -3. Click on "Restart crawling" +Example (after releasing 1.41, preparing for 1.42): +```json +{ + "cliVersion": "3.17.0", + "chartVersion": "1.42.0", + "syncthingVersion": "2.0.14" +} +``` -It should take a few minutes and the search index will be completed. +Create a PR with these changes: +```bash +git checkout main +git pull +git checkout -b prepare-variables-1.XX +# Update variables.json +git add src/content/variables.json +git commit -m "Prepare variables for version 1.XX development" +git push -u origin prepare-variables-1.XX +``` -Update `src/content/variables.json` by incrementing the values of `cliVersion` and `chartVersion` to reflect the upcoming release versions. +Then create a pull request for review before merging to main. ## Components