From ec81883c28d60e4fa991eca92b226aadd5f6224c Mon Sep 17 00:00:00 2001 From: AR21SM Date: Mon, 1 Sep 2025 18:19:43 +0530 Subject: [PATCH 1/2] docs: version release documentation with step-by-step instructions --- Version release guide.md | 225 +++++++++++++++++++++++++++++++++++++++ index.html | 12 +++ 2 files changed, 237 insertions(+) create mode 100644 Version release guide.md diff --git a/Version release guide.md b/Version release guide.md new file mode 100644 index 000000000..4ec62d645 --- /dev/null +++ b/Version release guide.md @@ -0,0 +1,225 @@ +# 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" + }, + { + "code": "hi", + "name_local": "हिन्दी", + "direction": "ltr" + } +] +``` + +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" + // "hidden": true was removed to make Spanish visible + }, + { + "code": "hi", + "name_local": "हिन्दी", + "direction": "ltr" + // New language added + } +] +``` + +> **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 + + Read the Cookbook +``` + +### Update the Latest Version Section (around line 98) + +Replace the existing "Latest" version card with your new version: + +```html + +
+
+
+ + +

Version X.Y

+ Latest +
+

The current stable release, recommended for all users. Includes the latest best practices and comprehensive updates.

+
+ + English + Español + + हिन्दी +
+
+
+``` + +### Move the Previous Version to Second Position (around line 116) + +Find the current "Latest" version and change it to look like this: + +```html + +
+
+
+ + +

Version 2.0

+
+

Previous stable release, archived for reference.

+
+ + English + Español + +
+
+
+``` +## 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 +# Switch back to main +git checkout main + +# Merge the changes +git merge X.Y-translations + +# Push the updated main branch +git push origin main +``` + +## 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 \ No newline at end of file diff --git a/index.html b/index.html index 865919c67..40a07e259 100644 --- a/index.html +++ b/index.html @@ -57,7 +57,10 @@

Welcome to DISCOVER Cookbook

Your comprehensive guide to creating diverse, inclusive, and accessible conferences and events in the tech sector

+ Read the Cookbook + + Contribute
@@ -91,6 +94,9 @@

How to Use This Cookbook

Available Versions

+ + +
@@ -105,6 +111,10 @@

Version 2.0

+ + + +
@@ -115,6 +125,8 @@

Version 1.0

English
+ +
From d131b99d5b7cf59cb9050fc2d4ced976409a25ff Mon Sep 17 00:00:00 2001 From: AR21SM Date: Sun, 14 Sep 2025 19:33:56 +0530 Subject: [PATCH 2/2] update: Release guide --- Version release guide.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/Version release guide.md b/Version release guide.md index 4ec62d645..99192855b 100644 --- a/Version release guide.md +++ b/Version release guide.md @@ -62,13 +62,15 @@ Edit `DISCOVER/_static/languages.json` to manage available languages. { "code": "es", "name_local": "Español", - "direction": "ltr" + "direction": "ltr", + "hidden": true // Removed this to make Spanish visible }, { "code": "hi", "name_local": "हिन्दी", "direction": "ltr" } + // Add New language ] ``` @@ -92,13 +94,11 @@ For example, to unhide Spanish and add Hindi: "code": "es", "name_local": "Español", "direction": "ltr" - // "hidden": true was removed to make Spanish visible }, { "code": "hi", "name_local": "हिन्दी", "direction": "ltr" - // New language added } ] ``` @@ -204,14 +204,18 @@ Check the **GitHub Actions** tab to monitor progress. After the release is deployed and verified: ```bash -# Switch back to main -git checkout main - -# Merge the changes -git merge X.Y-translations - -# Push the updated main branch -git push origin main +#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