Organize documentation by version on the Readme Portal #9269
+330
−34
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,153 @@ | ||
| #!/bin/bash | ||
| # Script to create a new ReadMe version when a new release tag is pushed. | ||
| # Usage: create-readme-version.sh <version_from_file> | ||
| # | ||
| # The version_from_file should be like "26.06.2" (without the v prefix). | ||
| # The script reads the .version file, determines the ReadMe version name, | ||
| # and creates it if it doesn't exist. | ||
|
|
||
| set -euo pipefail | ||
|
|
||
| VERSION="${1:-}" | ||
| if [ -z "$VERSION" ]; then | ||
| # Try reading from .version file | ||
| if [ -f .version ]; then | ||
| FULL_VERSION=$(cat .version | tr -d ' \n') | ||
| VERSION="${FULL_VERSION#v}" | ||
| else | ||
| echo "❌ No version provided and no .version file found." | ||
| exit 1 | ||
| fi | ||
| fi | ||
|
|
||
| # Strip 'v' prefix if present | ||
| VERSION="${VERSION#v}" | ||
|
|
||
| if [ -z "$VERSION" ]; then | ||
| echo "❌ Could not determine version." | ||
| exit 1 | ||
| fi | ||
|
|
||
| echo "📋 Version from .version file: v${VERSION}" | ||
|
|
||
| # Determine the short version (e.g., "26.06" from "26.06.2") | ||
| SHORT_VERSION=$(echo "$VERSION" | grep -oE '^[0-9]+\.[0-9]+') | ||
| echo "📋 Short version for ReadMe: ${SHORT_VERSION}" | ||
|
|
||
| # Check for RC releases | ||
| IS_RC=false | ||
| if echo "$VERSION" | grep -qi "rc"; then | ||
| IS_RC=true | ||
| echo "📋 This is a Release Candidate" | ||
| fi | ||
|
|
||
| # The ReadMe API key is required | ||
| README_API_KEY="${README_API_KEY:-}" | ||
| if [ -z "$README_API_KEY" ]; then | ||
| echo "❌ README_API_KEY environment variable not set." | ||
| exit 1 | ||
| fi | ||
|
|
||
| # Check if a version/branch already exists in ReadMe | ||
| echo "🔍 Checking if version '${SHORT_VERSION}' exists in ReadMe..." | ||
|
|
||
| EXISTING_VERSIONS=$(curl -s -X GET "https://api.readme.com/v2/branches" \ | ||
| -H "Authorization: Bearer ${README_API_KEY}") | ||
|
|
||
| VERSION_EXISTS=$(echo "$EXISTING_VERSIONS" | python3 -c " | ||
| import json, sys | ||
| try: | ||
| data = json.load(sys.stdin) | ||
| versions = [] | ||
| for item in data.get('data', []): | ||
| versions.append(item.get('name', '')) | ||
| if '${SHORT_VERSION}' in versions: | ||
| print('true') | ||
| else: | ||
| print('false') | ||
| except: | ||
| print('false') | ||
| ") | ||
|
|
||
| if [ "$VERSION_EXISTS" = "true" ]; then | ||
| echo "✅ Version '${SHORT_VERSION}' already exists in ReadMe. Skipping creation." | ||
| echo "readme_version_exists=true" >> "$GITHUB_OUTPUT" | ||
| echo "readme_version=${SHORT_VERSION}" >> "$GITHUB_OUTPUT" | ||
| echo "readme_version_created=false" >> "$GITHUB_OUTPUT" | ||
| exit 0 | ||
| fi | ||
|
|
||
| echo "🆕 Creating new ReadMe version '${SHORT_VERSION}'..." | ||
|
|
||
| # Determine which version to fork from | ||
| # Try to find the most recent stable version in the same major.minor series | ||
| FORK_VERSION="stable" | ||
| echo "🔍 Looking for a base version to fork from..." | ||
|
|
||
| # Find the latest existing version in ReadMe as potential base | ||
| BASE_VERSION=$(echo "$EXISTING_VERSIONS" | python3 -c " | ||
| import json, sys | ||
| try: | ||
| data = json.load(sys.stdin) | ||
| names = [] | ||
| for item in data.get('data', []): | ||
| name = item.get('name', '') | ||
| # Prefer non-'master' versions as base | ||
| if name and 'master' not in name: | ||
| names.append(name) | ||
| # Get the last one (assuming sorted order) | ||
|
Collaborator
There was a problem hiding this comment. Can we assume that? What if our releases were in this chronological order: v26.04 v26.06 v26.04.1 v26.06.1 ? |
||
| if names: | ||
| print(names[-1]) | ||
| else: | ||
| print('') | ||
| except: | ||
| print('') | ||
| ") | ||
|
|
||
| if [ -n "$BASE_VERSION" ] && [ "$BASE_VERSION" != "$SHORT_VERSION" ]; then | ||
| FORK_VERSION="$BASE_VERSION" | ||
| fi | ||
|
|
||
| echo "📋 Forking from version: '${FORK_VERSION}'" | ||
|
|
||
| # Create the new version via ReadMe API | ||
| # POST /v2/versions | ||
| CREATE_RESPONSE=$(curl -s -X POST "https://api.readme.com/v2/versions" \ | ||
|
Collaborator
There was a problem hiding this comment. I think this is legacy API and in v2 it is all about branches, not versions: https://docs.readme.com/main/reference/api-upgrade-guide#versions Also same here with |
||
| -H "Authorization: Bearer ${README_API_KEY}" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d "{ | ||
| \"version\": \"${SHORT_VERSION}\", | ||
| \"version_clean\": \"${SHORT_VERSION}\", | ||
| \"fork\": \"${FORK_VERSION}\", | ||
| \"is_stable\": false, | ||
| \"is_beta\": ${IS_RC}, | ||
| \"is_deprecated\": false | ||
| }") | ||
|
|
||
| echo "📋 Create response: $CREATE_RESPONSE" | ||
|
|
||
| # Check if creation succeeded | ||
| CREATE_STATUS=$(echo "$CREATE_RESPONSE" | python3 -c " | ||
| import json, sys | ||
| try: | ||
| data = json.load(sys.stdin) | ||
| if 'version' in data: | ||
| print('success') | ||
| else: | ||
| print('failed:', data.get('error', 'unknown error')) | ||
| except Exception as e: | ||
| print('parse error:', str(e)) | ||
| ") | ||
|
|
||
| if echo "$CREATE_STATUS" | grep -q "success"; then | ||
| echo "✅ Successfully created ReadMe version '${SHORT_VERSION}'" | ||
| echo "readme_version_exists=false" >> "$GITHUB_OUTPUT" | ||
| echo "readme_version=${SHORT_VERSION}" >> "$GITHUB_OUTPUT" | ||
| echo "readme_version_created=true" >> "$GITHUB_OUTPUT" | ||
| else | ||
| echo "❌ Failed to create ReadMe version: $CREATE_STATUS" | ||
| echo "readme_version_exists=false" >> "$GITHUB_OUTPUT" | ||
| echo "readme_version=${SHORT_VERSION}" >> "$GITHUB_OUTPUT" | ||
| echo "readme_version_created=false" >> "$GITHUB_OUTPUT" | ||
| exit 1 | ||
| fi | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,41 +1,100 @@ | ||
| name: ReadMe Docs Sync | ||
|
|
||
| on: | ||
| push: | ||
| branches: | ||
| - 'master' | ||
| paths: | ||
| - 'doc/**' | ||
| tags: | ||
| - 'v[0-9]+.[0-9]+' | ||
| - 'v[0-9]+.[0-9]+.[0-9]+' | ||
| - 'v[0-9]+.[0-9]+[0-9a-z]+' | ||
| workflow_dispatch: | ||
|
|
||
| jobs: | ||
| # Step 1: Determine version and create ReadMe version if needed | ||
| version: | ||
| name: Determine ReadMe Version | ||
| runs-on: ubuntu-24.04 | ||
| outputs: | ||
| readme_version: ${{ steps.determine.outputs.readme_version }} | ||
| version_created: ${{ steps.create_version.outputs.readme_version_created }} | ||
| steps: | ||
| - name: Check out repo 📚 | ||
| uses: actions/checkout@v6 | ||
|
|
||
| - name: Determine version from .version file | ||
| id: determine | ||
| run: | | ||
| if [ -f .version ]; then | ||
| FULL_VERSION=$(cat .version | tr -d ' \n') | ||
| VERSION="${FULL_VERSION#v}" | ||
| SHORT_VERSION=$(echo "$VERSION" | grep -oE '^[0-9]+\.[0-9]+') | ||
| echo "Full version: $FULL_VERSION" | ||
| echo "Short version: $SHORT_VERSION" | ||
| echo "readme_version=${SHORT_VERSION}" >> "$GITHUB_OUTPUT" | ||
| else | ||
| echo "No .version file found, using 'stable'" | ||
| echo "readme_version=stable" >> "$GITHUB_OUTPUT" | ||
| fi | ||
|
|
||
| - name: Create ReadMe version if needed | ||
| id: create_version | ||
| if: github.ref_type == 'tag' | ||
| run: | | ||
| bash .github/scripts/create-readme-version.sh "${{ steps.determine.outputs.readme_version }}" | ||
| env: | ||
| README_API_KEY: ${{ secrets.README_API_KEY }} | ||
|
|
||
| # Step 2: Sync docs to the determined version | ||
| rdme-docs-sync: | ||
| name: Sync Docs to ReadMe | ||
| needs: version | ||
| runs-on: ubuntu-24.04 | ||
| steps: | ||
| - name: Check out repo 📚 | ||
| uses: actions/checkout@v6 | ||
|
|
||
| - name: Read version for sync | ||
| id: sync_version | ||
| run: | | ||
| README_VERSION="${{ needs.version.outputs.readme_version }}" | ||
| if [ -z "$README_VERSION" ] || [ "$README_VERSION" = "null" ]; then | ||
| if [ -f .version ]; then | ||
| FULL_VERSION=$(cat .version | tr -d ' \n') | ||
| VERSION="${FULL_VERSION#v}" | ||
| README_VERSION=$(echo "$VERSION" | grep -oE '^[0-9]+\.[0-9]+') | ||
| else | ||
| README_VERSION="stable" | ||
| fi | ||
| fi | ||
| echo "Syncing to ReadMe version: ${README_VERSION}" | ||
| echo "version=${README_VERSION}" >> "$GITHUB_OUTPUT" | ||
| - name: Sync doc/getting-started/ 🚀 | ||
| uses: readmeio/rdme@v10 | ||
| with: | ||
| rdme: docs upload ./doc/getting-started --key=${{ secrets.README_API_KEY }} --branch=${{ steps.sync_version.outputs.version }} | ||
|
|
||
| - name: Sync doc/beginners-guide/ 🚀 | ||
| uses: readmeio/rdme@v10 | ||
| with: | ||
| rdme: docs upload ./doc/beginners-guide --key=${{ secrets.README_API_KEY }} --branch=${{ steps.sync_version.outputs.version }} | ||
|
|
||
| - name: Sync doc/node-operators-guide/ 🚀 | ||
| uses: readmeio/rdme@v10 | ||
| with: | ||
| rdme: docs upload ./doc/node-operators-guide --key=${{ secrets.README_API_KEY }} --branch=${{ steps.sync_version.outputs.version }} | ||
|
|
||
| - name: Sync doc/developers-guide/ 🚀 | ||
| uses: readmeio/rdme@v10 | ||
| with: | ||
| rdme: docs upload ./doc/developers-guide --key=${{ secrets.README_API_KEY }} --branch=${{ steps.sync_version.outputs.version }} | ||
|
|
||
| - name: Sync doc/contributing-to-core-lightning/ 🚀 | ||
| uses: readmeio/rdme@v10 | ||
| with: | ||
| rdme: docs upload ./doc/contribute-to-core-lightning --key=${{ secrets.README_API_KEY }} --branch=${{ steps.sync_version.outputs.version }} | ||
|
|
||
| # Note: Promotion to stable is handled in readme-rpc-sync.yml to avoid race | ||
| # conditions between the two workflows publishing to the same ReadMe project. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should probably add
--retry xand--fail. Without--failwe might think a version does not exists when in reality we just could not get a network response here.