Skip to content

Commit 64acbac

Browse files
Copilotdannywillems
andcommitted
Add documentation for creating versions for previous releases
Co-authored-by: dannywillems <6018454+dannywillems@users.noreply.github.com>
1 parent 170085c commit 64acbac

File tree

1 file changed

+104
-0
lines changed

1 file changed

+104
-0
lines changed

website/docs/appendix/documentation-versioning.mdx

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,110 @@ This command:
4747
- Updates `website/versions.json` to include the new version
4848
- Makes the version available in the dropdown menu
4949

50+
### Creating a Version for a Previous Release
51+
52+
Sometimes you need to create documentation versions for releases that were made
53+
before the versioning system was implemented. This process involves checking out
54+
the specific commit for that release and creating the version from that
55+
historical state.
56+
57+
#### Step-by-Step Process
58+
59+
1. **Find the release commit or tag**:
60+
61+
```bash
62+
# Look for the specific release tag
63+
git tag --list | grep v0.17.0
64+
65+
# Or find the commit hash for the release
66+
git log --oneline --grep="v0.17.0" --grep="Release.*0.17.0"
67+
```
68+
69+
2. **Create a temporary branch from the release commit**:
70+
71+
```bash
72+
# If you have a tag for v0.17.0
73+
git checkout -b temp-v0.17.0-docs v0.17.0
74+
75+
# Or if you have the commit hash
76+
git checkout -b temp-v0.17.0-docs <commit-hash>
77+
```
78+
79+
3. **Install documentation dependencies**:
80+
81+
```bash
82+
cd website
83+
npm install
84+
```
85+
86+
4. **Create the version from the historical documentation**:
87+
88+
```bash
89+
# Create version 0.17.0 from the current (historical) docs
90+
npm run docusaurus docs:version 0.17.0
91+
```
92+
93+
5. **Copy the versioned files to your main branch**:
94+
95+
```bash
96+
# Switch back to your main development branch
97+
git checkout develop # or main
98+
99+
# Copy the versioned documentation files
100+
cp -r /path/to/temp-branch/website/versioned_docs/version-0.17.0/ website/versioned_docs/
101+
cp /path/to/temp-branch/website/versioned_sidebars/version-0.17.0-sidebars.json website/versioned_sidebars/
102+
103+
# Update versions.json to include the new version
104+
# Edit website/versions.json to add "0.17.0" to the array
105+
```
106+
107+
6. **Clean up the temporary branch**:
108+
109+
```bash
110+
git branch -D temp-v0.17.0-docs
111+
```
112+
113+
7. **Verify and commit the changes**:
114+
115+
```bash
116+
# Test that the documentation builds correctly
117+
make docs-build-only
118+
119+
# Commit the versioned documentation
120+
git add website/versioned_docs/version-0.17.0/
121+
git add website/versioned_sidebars/version-0.17.0-sidebars.json
122+
git add website/versions.json
123+
git commit -m "Add documentation version for v0.17.0"
124+
```
125+
126+
#### Example: Creating v0.17.0 Documentation
127+
128+
```bash
129+
# Example workflow for creating v0.17.0 documentation
130+
git checkout -b temp-v0.17.0-docs v0.17.0
131+
cd website && npm install
132+
npm run docusaurus docs:version 0.17.0
133+
git checkout develop
134+
cp -r ../temp-v0.17.0-docs/website/versioned_docs/version-0.17.0/ website/versioned_docs/
135+
cp ../temp-v0.17.0-docs/website/versioned_sidebars/version-0.17.0-sidebars.json website/versioned_sidebars/
136+
# Edit website/versions.json to add "0.17.0"
137+
git branch -D temp-v0.17.0-docs
138+
make docs-build-only
139+
```
140+
141+
#### Important Notes for Previous Releases
142+
143+
- **Documentation State**: The versioned documentation will reflect the exact
144+
state of the docs at that historical commit
145+
- **Missing Features**: If the historical documentation was incomplete or
146+
missing, the versioned docs will also be incomplete
147+
- **Broken Links**: Links that reference newer features or pages may be broken
148+
in historical versions
149+
- **Manual Editing**: You may need to manually edit the versioned documentation
150+
to fix any issues specific to that release
151+
- **Testing**: Always test the documentation build after adding historical
152+
versions
153+
50154
### Listing Available Versions
51155

52156
```bash

0 commit comments

Comments
 (0)