Skip to content

Improve version release documentation for agent automation #1159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
codyjlandstrom wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve version release documentation for agent automation #1159

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
298 changes: 219 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<OFFICIAL_VERSION>/` redirects to `/docs` and `/docs/unreleased/` redirects to `/docs/<CURRENT_VERSION>`.
### 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

Expand Down