diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 52dcbf14a..bfaddb9f4 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -14,7 +14,7 @@ env: concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} - cancel-in-progress: true + cancel-in-progress: ${{ github.ref != 'refs/heads/develop' && !startsWith(github.ref, 'refs/tags/v') }} jobs: # Test documentation build @@ -122,17 +122,28 @@ jobs: id: deployment uses: actions/deploy-pages@v4 - # Create versioned documentation on tag creation + # Create and deploy versioned documentation on tag creation version-docs: if: startsWith(github.ref, 'refs/tags/v') - needs: [build-docs] runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + permissions: + contents: read + pages: write + id-token: write + steps: - name: Checkout repository uses: actions/checkout@v5 with: fetch-depth: 0 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Setup Node.js uses: actions/setup-node@v5 with: @@ -161,10 +172,19 @@ jobs: sudo apt update sudo apt install -y protobuf-compiler + - name: Setup Rust + uses: dtolnay/rust-toolchain@stable + with: + components: rustfmt + # This should be in line with the verison in: + # - Makefile + # - ./github/workflows/docs.yaml + # - ./github/workflows/fmt.yaml + # - ./github/workflows/lint.yaml + toolchain: nightly + - name: Build versioned documentation - run: | - cd website - npm run build + run: make docs-build env: NODE_ENV: production @@ -182,3 +202,12 @@ jobs: path: | mina-docs-${{ steps.version.outputs.version }}.tar.gz mina-docs-${{ steps.version.outputs.version }}.zip + + - name: Upload to GitHub Pages + uses: actions/upload-pages-artifact@v4 + with: + path: website/build + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/Makefile b/Makefile index 7dfd19e16..90f860239 100644 --- a/Makefile +++ b/Makefile @@ -536,6 +536,40 @@ docs-clean: ## Clean documentation build artifacts @rm -rf website/build website/.docusaurus website/static/api-docs target/doc @echo "Documentation artifacts cleaned!" +# Documentation versioning targets + +.PHONY: docs-version-create +docs-version-create: docs-install ## Create a new documentation version (requires VERSION=x.y.z) + @if [ -z "$(VERSION)" ]; then \ + echo "Error: VERSION is required. Usage: make docs-version-create VERSION=1.2.3"; \ + exit 1; \ + fi + @echo "Creating documentation version $(VERSION)..." + @cd website && npx docusaurus docs:version "$(VERSION)" + @echo "Documentation version $(VERSION) created successfully!" + @echo "Files created in website/versioned_docs/version-$(VERSION)/" + +.PHONY: docs-version-list +docs-version-list: docs-install ## List all documentation versions + @echo "Available documentation versions:" + @cd website && if [ -f versions.json ]; then cat versions.json | jq -r '.[]' | sed 's/^/ - /'; else echo " No versions found. Current version only."; fi + +.PHONY: docs-version-clean +docs-version-clean: ## Clean all versioned documentation (WARNING: destructive) + @echo "WARNING: This will remove all versioned documentation!" + @echo "Files to be removed:" + @echo " - website/versioned_docs/" + @echo " - website/versioned_sidebars/" + @echo " - website/versions.json" + @echo "" + @echo "Use 'make docs-version-clean-force' to proceed without confirmation" + +.PHONY: docs-version-clean-force +docs-version-clean-force: ## Force clean all versioned documentation (no confirmation) + @echo "Removing all versioned documentation..." + @rm -rf website/versioned_docs website/versioned_sidebars website/versions.json + @echo "All versioned documentation removed!" + # Release management targets .PHONY: release-validate @@ -571,6 +605,14 @@ release-create-tag: ## Create and push git tag (requires TAG=version MESSAGE="de release-merge-back: ## Merge main back to develop after release @website/docs/developers/scripts/release/merge-back.sh +.PHONY: release-docs-version +release-docs-version: ## Create documentation version for release (requires VERSION=x.y.z) + @if [ -z "$(VERSION)" ]; then \ + echo "Error: VERSION is required. Usage: make release-docs-version VERSION=1.2.3"; \ + exit 1; \ + fi + @make docs-version-create VERSION="$(VERSION)" + .PHONY: release-help release-help: ## Show release management commands @echo "Release Management Commands:" @@ -579,12 +621,21 @@ release-help: ## Show release management commands @echo " release-update-version - Update Cargo.toml versions (requires VERSION=x.y.z)" @echo " release-create-tag - Create and push git tag (requires TAG=vx.y.z MESSAGE='...')" @echo " release-docker-verify - Verify Docker images (requires TAG=vx.y.z)" + @echo " release-docs-version - Create documentation version (requires VERSION=x.y.z)" @echo " release-merge-back - Merge main back to develop" @echo "" + @echo "Documentation Versioning Commands:" + @echo "" + @echo " docs-version-create - Create new docs version (requires VERSION=x.y.z)" + @echo " docs-version-list - List all documentation versions" + @echo " docs-version-clean - Show files that would be removed (safe)" + @echo " docs-version-clean-force - Remove all versioned docs (WARNING: destructive)" + @echo "" @echo "Example workflow:" @echo " make release-validate" @echo " make release-update-version VERSION=1.2.3" @echo " # Create PR, get approval, merge to main" @echo " make release-create-tag TAG=v1.2.3 MESSAGE='Release v1.2.3'" + @echo " make release-docs-version VERSION=1.2.3" @echo " make release-docker-verify TAG=v1.2.3" @echo " make release-merge-back" diff --git a/website/docs/appendix/documentation-versioning.mdx b/website/docs/appendix/documentation-versioning.mdx new file mode 100644 index 000000000..c65fe372d --- /dev/null +++ b/website/docs/appendix/documentation-versioning.mdx @@ -0,0 +1,277 @@ +--- +title: Documentation Versioning +description: + Guide to managing and using versioned documentation in the Mina Rust project +sidebar_position: 3 +--- + +# Documentation Versioning + +The Mina Rust documentation uses +[Docusaurus versioning](https://docusaurus.io/docs/versioning) to maintain +documentation for multiple releases. This allows users to access documentation +for specific versions of the software. + +## How Versioning Works + +### Version Structure + +- **Current Version (`develop`)**: The latest development documentation, + available at the root path (`/docs/`) +- **Released Versions**: Specific release versions (e.g., `1.0.0`), available at + versioned paths (`/docs/1.0.0/`) + +### Accessing Different Versions + +Users can switch between documentation versions using the version dropdown in +the navigation bar. Each version maintains its own complete documentation tree. + +## Managing Documentation Versions + +### Creating a New Version + +Create a new documentation version during the release process: + +```bash +# Create version for release 1.2.3 +make docs-version-create VERSION=1.2.3 + +# Or as part of the release workflow +make release-docs-version VERSION=1.2.3 +``` + +This command: + +- Takes a snapshot of the current `docs/` directory +- Creates versioned copies in `website/versioned_docs/version-1.2.3/` +- Updates `website/versions.json` to include the new version +- Makes the version available in the dropdown menu + +### Creating a Version for a Previous Release + +Sometimes you need to create documentation versions for releases that were made +before the versioning system was implemented. This process involves checking out +the specific commit for that release and creating the version from that +historical state. + +#### Step-by-Step Process + +1. **Find the release commit or tag**: + + ```bash + # Look for the specific release tag + git tag --list | grep v0.17.0 + + # Or find the commit hash for the release + git log --oneline --grep="v0.17.0" --grep="Release.*0.17.0" + ``` + +2. **Create a temporary branch from the release commit**: + + ```bash + # If you have a tag for v0.17.0 + git checkout -b temp-v0.17.0-docs v0.17.0 + + # Or if you have the commit hash + git checkout -b temp-v0.17.0-docs + ``` + +3. **Install documentation dependencies**: + + ```bash + cd website + npm install + ``` + +4. **Create the version from the historical documentation**: + + ```bash + # Create version 0.17.0 from the current (historical) docs + npm run docusaurus docs:version 0.17.0 + ``` + +5. **Copy the versioned files to your main branch**: + + ```bash + # Switch back to your main development branch + git checkout develop # or main + + # Copy the versioned documentation files + cp -r /path/to/temp-branch/website/versioned_docs/version-0.17.0/ website/versioned_docs/ + cp /path/to/temp-branch/website/versioned_sidebars/version-0.17.0-sidebars.json website/versioned_sidebars/ + + # Update versions.json to include the new version + # Edit website/versions.json to add "0.17.0" to the array + ``` + +6. **Clean up the temporary branch**: + + ```bash + git branch -D temp-v0.17.0-docs + ``` + +7. **Verify and commit the changes**: + + ```bash + # Test that the documentation builds correctly + make docs-build-only + + # Commit the versioned documentation + git add website/versioned_docs/version-0.17.0/ + git add website/versioned_sidebars/version-0.17.0-sidebars.json + git add website/versions.json + git commit -m "Add documentation version for v0.17.0" + ``` + +#### Example: Creating v0.17.0 Documentation + +```bash +# Example workflow for creating v0.17.0 documentation +git checkout -b temp-v0.17.0-docs v0.17.0 +cd website && npm install +npm run docusaurus docs:version 0.17.0 +git checkout develop +cp -r ../temp-v0.17.0-docs/website/versioned_docs/version-0.17.0/ website/versioned_docs/ +cp ../temp-v0.17.0-docs/website/versioned_sidebars/version-0.17.0-sidebars.json website/versioned_sidebars/ +# Edit website/versions.json to add "0.17.0" +git branch -D temp-v0.17.0-docs +make docs-build-only +``` + +#### Important Notes for Previous Releases + +- **Documentation State**: The versioned documentation will reflect the exact + state of the docs at that historical commit +- **Missing Features**: If the historical documentation was incomplete or + missing, the versioned docs will also be incomplete +- **Broken Links**: Links that reference newer features or pages may be broken + in historical versions +- **Manual Editing**: You may need to manually edit the versioned documentation + to fix any issues specific to that release +- **Testing**: Always test the documentation build after adding historical + versions + +### Listing Available Versions + +```bash +# List all available documentation versions +make docs-version-list +``` + +### Cleaning Up Versions + +:::warning Destructive Operation This command permanently removes all versioned +documentation. Use with caution. ::: + +```bash +# Remove all versioned documentation (interactive confirmation) +make docs-version-clean +``` + +## Version Behavior + +### Current Version (develop) + +- Always shows the latest documentation from the `docs/` directory +- Available at the root documentation path +- Labeled as "develop" in the version dropdown +- No version banners or warnings + +### Released Versions + +- Snapshot of documentation at the time of release +- Available at `/docs/{version}/` paths +- Shows a banner indicating the version is no longer actively maintained +- Provides a link back to the current (develop) version + +### Version Dropdown + +The version dropdown in the navigation bar: + +- Lists all available versions +- Shows the current selection +- Allows quick switching between versions +- Maintains the current page context when switching (if the page exists in the + target version) + +## Best Practices + +### When to Create Versions + +- **Always** create a documentation version as part of the release process +- Create versions for major and minor releases +- Consider creating versions for significant patch releases with documentation + changes +- Do not create versions for minor documentation updates between releases + +### Maintaining Version Quality + +- Ensure documentation is complete and accurate before creating a version +- Test all links and examples in the documentation before versioning +- Update any version-specific information (installation instructions, + compatibility notes) + +### Documentation Updates + +- **Current documentation**: Edit files in `website/docs/` +- **Versioned documentation**: Edit files in + `website/versioned_docs/version-{version}/` +- **Sidebar configuration**: Versioned sidebars are stored in + `website/versioned_sidebars/` + +## File Structure + +``` +website/ +├── docs/ # Current (develop) documentation +├── versioned_docs/ +│ └── version-1.0.0/ # Versioned documentation +├── versioned_sidebars/ +│ └── version-1.0.0-sidebars.json # Versioned sidebars +└── versions.json # List of available versions +``` + +## Integration with Release Process + +Documentation versioning is integrated into the release workflow: + +1. **Version Creation**: Part of the release process after tag creation +2. **Automated**: Uses the same version number as the software release +3. **Consistent**: Ensures documentation versions match software versions +4. **Preserved**: Maintains historical documentation for all releases + +For complete release process details, see the +[Release Process](./release-process.mdx) guide. + +## Troubleshooting + +### Version Not Appearing in Dropdown + +1. Check that `website/versions.json` includes the version +2. Verify files exist in `website/versioned_docs/version-{version}/` +3. Rebuild the documentation site + +### Broken Links in Versioned Docs + +- Versioned documentation uses absolute paths within the version +- Links between versions are not automatically updated +- Test documentation thoroughly before creating versions + +### Large Repository Size + +- Versioned documentation duplicates content +- Consider the trade-off between version history and repository size +- Remove very old versions if repository size becomes problematic + +## Related Commands + +```bash +# Documentation building and serving +make docs-build # Build with API docs +make docs-serve # Serve locally with hot reload +make docs-clean # Clean build artifacts + +# Release integration +make release-help # Show all release commands +make release-docs-version VERSION=x.y.z # Create docs version for release +``` diff --git a/website/docs/appendix/release-process.mdx b/website/docs/appendix/release-process.mdx index 0576dd77b..d166874ac 100644 --- a/website/docs/appendix/release-process.mdx +++ b/website/docs/appendix/release-process.mdx @@ -82,6 +82,7 @@ Copy and paste this checklist when announcing a release in progress: - [ ] Required approvals obtained - [ ] PR merged to main - [ ] Git tag created and pushed +- [ ] Documentation version created - [ ] Docker images building (automated) - [ ] GitHub release draft created @@ -301,7 +302,44 @@ This automatically: - Creates an annotated tag with the provided message - Pushes the tag to origin (which triggers Docker image builds) -### 6. Create GitHub Release +### 6. Create Documentation Version + +```bash +# Create a versioned copy of the documentation +make release-docs-version VERSION=1.5.0 +``` + +This command: + +- Creates a snapshot of the current documentation under + `website/versioned_docs/version-1.5.0/` +- Preserves the exact state of documentation at the time of release +- Allows users to access documentation for previous versions +- Updates the version dropdown to include the new version + +The versioned documentation will be available at `/docs/1.5.0/` and can be +accessed through the version dropdown in the website navigation. + + + +:::info Automated CI Deployment + +When a release tag is created (e.g., `v1.5.0`), the GitHub Actions CI will +automatically: + +- Create a versioned copy of the documentation +- Build the documentation with the new version included +- Deploy the updated documentation to GitHub Pages +- Upload versioned documentation archives as release assets + +This means the documentation versioning and deployment is handled automatically +as part of the tag creation process. + +::: + + + +### 7. Create GitHub Release ```bash # Create GitHub release from tag @@ -317,7 +355,7 @@ gh release create v1.5.0 \ --draft ``` -### 7. Verify Automated Processes +### 8. Verify Automated Processes After pushing the tag, verify: @@ -353,7 +391,7 @@ After pushing the tag, verify: - Visit [Docker Hub - mina-rust-frontend](https://hub.docker.com/r/o1labs/mina-rust-frontend/tags) -### 8. Publish GitHub Release +### 9. Publish GitHub Release Once verification is complete: @@ -362,7 +400,7 @@ Once verification is complete: gh release edit v1.5.0 --draft=false ``` -### 9. Update Documentation +### 10. Update Documentation - Update any documentation that references version numbers - Announce release in relevant channels diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 74dc08fb6..0600dcfcc 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -52,6 +52,8 @@ const config: Config = { versions: { current: { label: 'develop', + path: '/', // Current version at root path + badge: true, }, }, // Enable edit links to GitHub diff --git a/website/sidebars.ts b/website/sidebars.ts index dcd3d33e8..f0306150b 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -164,6 +164,7 @@ const sidebars: SidebarsConfig = { label: 'Development Processes', items: [ 'appendix/release-process', + 'appendix/documentation-versioning', ], }, ],