diff --git a/.github/scripts/create-readme-version.sh b/.github/scripts/create-readme-version.sh new file mode 100755 index 000000000000..1742666cd4a8 --- /dev/null +++ b/.github/scripts/create-readme-version.sh @@ -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 +# +# 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) + 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" \ + -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 diff --git a/.github/scripts/sync-rpc-cmds.py b/.github/scripts/sync-rpc-cmds.py index eb915aab4805..1d73e5ee437f 100644 --- a/.github/scripts/sync-rpc-cmds.py +++ b/.github/scripts/sync-rpc-cmds.py @@ -4,8 +4,9 @@ import re from enum import Enum -# readme url -BRANCH = "stable" +# ReadMe version - use README_VERSION env var if set, otherwise default to "stable" +BRANCH = os.environ.get("README_VERSION", "stable") +print(f"📋 Using ReadMe version/branch: '{BRANCH}'") URL = f"https://api.readme.com/v2/branches/{BRANCH}" CATEGORY_SLUG = "JSON-RPC" NOTIFICATIONS_CATEGORY_SLUG = "Notifications" diff --git a/.github/workflows/rdme-docs-sync.yml b/.github/workflows/rdme-docs-sync.yml index 5d9dbd2aa605..3e6ec245b185 100644 --- a/.github/workflows/rdme-docs-sync.yml +++ b/.github/workflows/rdme-docs-sync.yml @@ -1,4 +1,4 @@ -name: ReadMe Sync +name: ReadMe Docs Sync on: push: @@ -6,36 +6,95 @@ on: - '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: - rdme-docs-sync: - runs-on: ubuntu-22.04 + # 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=1 - + 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=1 + 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=1 + 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=1 - + 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=1 + 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. diff --git a/.github/workflows/readme-rpc-sync.yml b/.github/workflows/readme-rpc-sync.yml index 855815b1fe9a..0f0cb3821013 100644 --- a/.github/workflows/readme-rpc-sync.yml +++ b/.github/workflows/readme-rpc-sync.yml @@ -13,36 +13,119 @@ on: - 'doc/*.8.md' - 'doc/lightningd-*.7.md' - 'doc/reckless.7.md' + 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: | + 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" + + - 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: Build and sync RPC docs to the determined version rdme-rpc-sync: - runs-on: ubuntu-22.04 + name: Sync RPC Docs to ReadMe + needs: version + runs-on: ubuntu-24.04 steps: - - name: Checkout repository - uses: actions/checkout@v6 + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: 3.9 + + - name: Install python modules + run: | + python -m pip install requests mako grpcio-tools - - name: Set up Python - uses: actions/setup-python@v6 - with: - python-version: 3.9 + - name: Install uv + uses: astral-sh/setup-uv@v8.1.0 - - name: Install python modules - run: | - python -m pip install requests mako grpcio-tools + - name: Install dependencies + run: bash -x .github/scripts/setup.sh + + - name: Build (including rpc .md files) + run: | + ./configure --enable-debugbuild + make -j $(nproc) + + - name: Determine ReadMe 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 RPC docs to ReadMe version: ${README_VERSION}" + echo "version=${README_VERSION}" >> "$GITHUB_OUTPUT" + + - name: Set environment variable and run + env: + README_API_KEY: ${{ secrets.README_API_KEY }} + README_VERSION: ${{ steps.sync_version.outputs.version }} + run: python .github/scripts/sync-rpc-cmds.py + + # Step 3: Set as stable version after sync (for full releases, not RC) + promote: + name: Promote to Stable + needs: + - version + - rdme-rpc-sync + if: > + github.ref_type == 'tag' && + needs.version.outputs.version_created == 'true' && !contains(github.ref_name, 'rc') + runs-on: ubuntu-24.04 + steps: + - name: Check out repo 📚 + uses: actions/checkout@v6 - - name: Install uv - uses: astral-sh/setup-uv@v8.1.0 + - name: Promote version to stable + run: | + README_VERSION="${{ needs.version.outputs.readme_version }}" + echo "Promoting '${README_VERSION}' to stable..." - - name: Install dependencies - run: bash -x .github/scripts/setup.sh + curl -s -X PUT "https://api.readme.com/v2/versions/${README_VERSION}" \ + -H "Authorization: Bearer ${{ secrets.README_API_KEY }}" \ + -H "Content-Type: application/json" \ + -d '{ + "is_stable": true + }' - - name: Build (including rpc .md files) - run: | - ./configure --enable-debugbuild - make -j $(nproc) + echo "" + echo "✅ Version '${README_VERSION}' promoted to stable!" - - name: Set environment variable and run - env: - README_API_KEY: ${{ secrets.README_API_KEY }} - run: python .github/scripts/sync-rpc-cmds.py