-
-
Notifications
You must be signed in to change notification settings - Fork 254
docs: version release documentation with step-by-step instructions #393
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.
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
AR21SM
wants to merge
2
commits into
numfocus:main
Choose a base branch
from
AR21SM:docs/version-management
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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,229 @@ | ||
| # DISCOVER Cookbook Version Release Guide | ||
|
|
||
| This guide walks you through the process of releasing a new version of the DISCOVER Cookbook. Follow these steps to ensure a smooth update when a new version is ready. | ||
|
|
||
| ## Step 1: Create a X.Y Version Tag and X.Y-translations Branch | ||
|
|
||
| First, create a X.Y version tag and a X.Y-translations branch specifically for the new version. This naming pattern is important - the system automatically detects branches ending with `-translations` and uses the prefix as the version number. | ||
|
|
||
| ```bash | ||
| # Create and checkout a new branch | ||
| git checkout -b X.Y-translations | ||
|
|
||
| # Push the branch to GitHub | ||
| git push origin X.Y-translations | ||
| ``` | ||
|
|
||
| ## Step 2: Update Version Configuration Files | ||
|
|
||
| ### Update the Versions List | ||
|
|
||
| Edit `DISCOVER/_static/versions.json` to include your new version. | ||
|
|
||
| ```json | ||
| [ | ||
| { | ||
| "version": "dev", | ||
| "url": "https://discover-cookbook.numfocus.org/dev/" | ||
| }, | ||
| { | ||
| "version": "X.Y", | ||
| "url": "https://discover-cookbook.numfocus.org/X.Y/", | ||
| "preferred": true | ||
| }, | ||
| { | ||
| "version": "2.0", | ||
| "url": "https://discover-cookbook.numfocus.org/2.0/" | ||
| }, | ||
| { | ||
| "version": "1.0", | ||
| "url": "https://discover-cookbook.numfocus.org/1.0/" | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| Make sure to: | ||
|
|
||
| * Add your new version entry. | ||
| * Move the `"preferred": true` flag to the new version. | ||
| * Keep the order from newest to oldest. | ||
|
|
||
| ### Update Language Settings | ||
|
|
||
| Edit `DISCOVER/_static/languages.json` to manage available languages. | ||
|
|
||
| ```json | ||
| [ | ||
| { | ||
| "code": "en", | ||
| "name_local": "English", | ||
| "direction": "ltr" | ||
| }, | ||
| { | ||
| "code": "es", | ||
| "name_local": "Español", | ||
| "direction": "ltr", | ||
| "hidden": true // Removed this to make Spanish visible | ||
| }, | ||
| { | ||
| "code": "hi", | ||
| "name_local": "हिन्दी", | ||
| "direction": "ltr" | ||
| } | ||
| // Add New language | ||
| ] | ||
| ``` | ||
|
|
||
| To manage language visibility and preferences: | ||
|
|
||
| * **Add a new language**: Add a new entry with the language code, local name, and text direction. | ||
| * **Make a language visible**: Remove the `"hidden": true` property from any language you want to show. | ||
| * **Hide a language**: Add `"hidden": true` to languages that aren't ready for public use. | ||
| * **Set default language**: The first non-hidden language is typically used as the default. | ||
|
|
||
| For example, to unhide Spanish and add Hindi: | ||
|
|
||
| ```json | ||
| [ | ||
| { | ||
| "code": "en", | ||
| "name_local": "English", | ||
| "direction": "ltr" | ||
| }, | ||
| { | ||
| "code": "es", | ||
| "name_local": "Español", | ||
| "direction": "ltr" | ||
| }, | ||
| { | ||
| "code": "hi", | ||
| "name_local": "हिन्दी", | ||
| "direction": "ltr" | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| > **Note**: When you add a new language, ensure all documentation files have been translated and placed in the appropriate directory in the `locales/` folder (e.g., `locales/hi/LC_MESSAGES/`). See the [`Translation.md`](Translation.md) file for how to update translatable sources. | ||
|
|
||
| ## Step 3: Update the Landing Page | ||
|
|
||
| Edit `index.html` to reflect the new version in these sections: | ||
|
|
||
| ### Update the Read the Cookbook Button (around line 60) | ||
|
|
||
| ```html | ||
| <!-- Update this URL to point to your new version --> | ||
| <a href="https://discover-cookbook.numfocus.org/X.Y/en/" class="btn btn-success btn-lg"><i class="bi bi-book"></i> Read the Cookbook</a> | ||
| ``` | ||
|
|
||
| ### Update the Latest Version Section (around line 98) | ||
|
|
||
| Replace the existing "Latest" version card with your new version: | ||
|
|
||
| ```html | ||
| <!-- Latest Version Card - Replace X.Y with your actual version number --> | ||
| <div class="col-lg-6"> | ||
| <div class="bg-success bg-opacity-10 p-4 rounded border border-success border-opacity-25 h-100"> | ||
| <div class="d-flex align-items-center mb-3"> | ||
| <i class="bi bi-star-fill text-warning me-2"></i> | ||
| <!-- UPDATE: Replace X.Y with your version number (e.g., Version 3.0) --> | ||
| <h4 class="mb-0">Version X.Y</h4> | ||
| <span class="badge bg-success ms-2">Latest</span> | ||
| </div> | ||
| <p class="text-muted mb-3">The current stable release, recommended for all users. Includes the latest best practices and comprehensive updates.</p> | ||
| <div class="d-flex flex-wrap gap-2"> | ||
| <!-- UPDATE: Replace X.Y with your version number in all URLs below --> | ||
| <a href="https://discover-cookbook.numfocus.org/X.Y/en" class="btn btn-success btn-sm">English</a> | ||
| <a href="https://discover-cookbook.numfocus.org/X.Y/es" class="btn btn-outline-secondary btn-sm">Español</a> | ||
| <!-- ADD: New language link (add this line if Hindi is available) --> | ||
| <a href="https://discover-cookbook.numfocus.org/X.Y/hi" class="btn btn-outline-secondary btn-sm">हिन्दी</a> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| ``` | ||
|
|
||
| ### Move the Previous Version to Second Position (around line 116) | ||
|
|
||
| Find the current "Latest" version and change it to look like this: | ||
|
|
||
| ```html | ||
| <!-- Previous Version Card - This should be the version that was previously "Latest" --> | ||
| <div class="col-lg-6"> | ||
| <div class="p-4 rounded h-100 border"> | ||
| <div class="d-flex align-items-center mb-3"> | ||
| <i class="bi bi-archive text-muted me-2"></i> | ||
| <!-- UPDATE: This should show the previous version number (e.g., Version 2.0) --> | ||
| <h4 class="mb-0">Version 2.0</h4> | ||
| </div> | ||
| <p class="text-muted mb-3">Previous stable release, archived for reference.</p> | ||
| <div class="d-flex flex-wrap gap-2"> | ||
| <!-- Keep existing language links for the previous version --> | ||
| <a href="https://discover-cookbook.numfocus.org/2.0/en" class="btn btn-outline-secondary btn-sm">English</a> | ||
| <a href="https://discover-cookbook.numfocus.org/2.0/es" class="btn btn-outline-secondary btn-sm">Español</a> | ||
| <!-- Only list languages that were supported in the previous version --> | ||
| </div> | ||
| </div> | ||
| </div> | ||
| ``` | ||
| ## Step 4: Commit and Push Changes | ||
|
|
||
| ```bash | ||
| # Add your changes | ||
| git add . | ||
|
|
||
| # Commit with a clear message | ||
| git commit -m "Release X.Y: Update version references and language settings" | ||
|
|
||
| # Push to the translation branch | ||
| git push origin X.Y-translations | ||
| ``` | ||
|
|
||
| ## Step 5: Create a X.Y Version Tag | ||
|
|
||
| ```bash | ||
| # Create a tag for the release | ||
| git tag -a X.Y -m "Release version X.Y" | ||
|
|
||
| # Push the tag to GitHub | ||
| git push origin X.Y | ||
| ``` | ||
|
|
||
| ## Step 6: Wait for Deployment | ||
|
|
||
| The GitHub Actions workflow will: | ||
|
|
||
| * Detect your new branch and tag. | ||
| * Build the documentation for each language. | ||
| * Deploy to the correct version path. | ||
| * Create redirect files. | ||
|
|
||
| Check the **GitHub Actions** tab to monitor progress. | ||
|
|
||
| ## Step 7: Merge Back to Main | ||
|
|
||
| After the release is deployed and verified: | ||
|
|
||
| ```bash | ||
| #After the release is deployed and verified, create a pull request to merge changes back to main | ||
| git checkout X.Y-translations | ||
|
|
||
| # Create a pull request | ||
| gh pr create --title "Release X.Y: Merge version updates to main" --body "This PR merges the version X.Y updates back to the main branch after successful deployment." | ||
|
|
||
| # Or manually create a PR through GitHub web interface: | ||
| # 1. Go to https://github.com/numfocus/DISCOVER-Cookbook | ||
| # 2. Click "New Pull Request" | ||
| # 3. Set base: main, compare: X.Y-translations | ||
| # 4. Add a descriptive title and description | ||
| # 5. Create a Pull Request | ||
| ``` | ||
|
|
||
| ## Step 8: Verify the Release | ||
|
|
||
| Check these links to confirm everything is working: | ||
|
|
||
| * **Main version**: `https://discover-cookbook.numfocus.org/X.Y/en/` | ||
| * **Landing page**: `https://discover-cookbook.numfocus.org/` | ||
| * Version switcher works in the documentation. | ||
| * All language options appear correctly in the language switcher. | ||
| * Confirm a banner appears on old versions linking to the | ||
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
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.
for visibility it might be better to have this done in a
prepare-releasebranch (or whatever name we like) and then open a PR intomainso main is updated from the get-go and we then create tag and release branch from main. That being said, I am not so familiar with the workflows in this repo so @aterrel should probably weigh in.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.
Waiting for @aterrel’s comment before making changes.