From d5ba460e73fa68e5987a87f9e4533382c847e3bc Mon Sep 17 00:00:00 2001
From: GitLab CI Runner <trini@konsulko.com>
Date: Thu, 11 Sep 2025 21:51:30 -0600
Subject: [PATCH] docs: Add concept release documentation and tracking

Add docs for the new concept release system:

- concept_cycle.rst: Technical documentation explaining the release
  mechanism, schedule calculations, and troubleshooting guide
- concept_releases.rst: Auto-updated release history file with
  installation instructions and real-time schedule generation
- Updated index.rst to include both new documentation files

The documentation covers:
- Bimonthly release schedule (Feb, Apr, Jun, Aug, Oct, Dec)
- RC numbering system counting backwards from final releases
- Dead period handling for dates too early in cycle
- Snap package distribution via Ubuntu Store
- Automated release tracking and history

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <sjg@chromium.org)
---
 doc/develop/concept_cycle.rst    | 200 +++++++++++++++++++++++++++++++
 doc/develop/concept_releases.rst |  52 ++++++++
 doc/develop/index.rst            |   2 +
 3 files changed, 254 insertions(+)
 create mode 100644 doc/develop/concept_cycle.rst
 create mode 100644 doc/develop/concept_releases.rst

diff --git a/doc/develop/concept_cycle.rst b/doc/develop/concept_cycle.rst
new file mode 100644
index 00000000000..4cb0b73eef8
--- /dev/null
+++ b/doc/develop/concept_cycle.rst
@@ -0,0 +1,200 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Concept Release Mechanism
+=========================
+
+This document describes the concept release mechanism for U-Boot, which provides
+automated builds and distribution through Ubuntu Snap packages.
+
+Overview
+--------
+
+The concept release mechanism automatically triggers builds of concept packages
+when changes are pushed to the master branch. This system uses two main components:
+
+1. **GitLab CI trigger job** - Automatically runs when master is updated
+2. **Launchpad snap builds** - Creates distributable packages
+
+Architecture
+------------
+
+The release workflow consists of:
+
+**Source Repository (GitLab)**
+   - Main U-Boot development happens here
+   - Contains `.gitlab-ci.yml` with `trigger_snap_builds` job
+   - Triggers downstream builds when master branch is updated
+
+**Concept Repositories (Launchpad)**
+   - `u-boot-concept-qemu` - QEMU-based U-Boot builds
+   - `u-boot-concept-efi` - EFI-based U-Boot builds
+   - Contain snap packaging configuration
+   - Build and publish to Ubuntu Snap Store
+
+Release Schedule
+----------------
+
+Concept releases follow an automated schedule based on calendar dates:
+
+**Final Releases**
+   - **When**: First Monday of even-numbered months (February, April, June, August, October, December)
+   - **Frequency**: 6 times per year
+   - **Version Format**: `YYYY.MM` (e.g., `2025.02`, `2025.04`)
+   - **Makefile**: VERSION and PATCHLEVEL updated, SUBLEVEL and EXTRAVERSION cleared
+
+**Release Candidates (RC)**
+   - **When**: All other scheduled pipeline runs before final releases
+   - **Frequency**: Up to 3 times per release cycle
+   - **Version Format**: `YYYY.MM-rcN` (e.g., `2025.02-rc1`, `2025.02-rc2`)
+   - **RC Numbering**: Counts backwards from final release date
+     
+     - **rc1**: 2 weeks before final release
+     - **rc2**: 4 weeks before final release  
+     - **rc3**: 6 weeks before final release
+     - **Maximum**: rc3 (never rc4 or higher)
+
+**Trigger Mechanism**
+   - Releases are triggered by **scheduled pipelines** only
+   - Must target the `master` branch
+   - Automatic version bumping updates the `Makefile`
+   - Git tags created: standard tag (`2025.02`) + c-prefixed tag (`c2025.02`)
+
+**Pipeline Stages**
+   1. `version_bump` stage: Updates Makefile and commits version
+   2. `release` stage: Creates GitLab release and tags when version commit detected
+
+Concept Snap Build Process
+---------------------------
+
+The concept snap builds are separate from the scheduled releases and trigger
+automatically when changes are pushed to the master branch:
+
+1. **GitLab CI Pipeline**
+   
+   The `trigger_snap_builds` job executes in the `release` stage:
+   
+   * Authenticates with Launchpad using SSH key
+   * Clones both concept repositories
+   * Creates empty commits with trigger messages
+   * Pushes commits to trigger Launchpad builds
+
+2. **Launchpad Build Process**
+   
+   Each triggered repository:
+   
+   * Detects the new commit
+   * Starts automated snap build process  
+   * Pulls latest U-Boot source code
+   * Builds snap packages for multiple architectures
+   * Publishes successful builds to Ubuntu Snap Store
+
+Configuration
+-------------
+
+GitLab CI Setup
+~~~~~~~~~~~~~~~~
+
+The trigger job requires these GitLab CI/CD variables:
+
+* `LAUNCHPAD_SSH_KEY` - SSH private key for Launchpad authentication
+  
+  - Must be set as a **Protected** variable
+  - Should contain the full SSH private key including headers
+  - Format: Standard OpenSSH private key with newlines
+
+SSH Key Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+The SSH key must be:
+
+* Associated with a Launchpad account that has push access to concept repos
+* Added to GitLab as a protected CI/CD variable
+* Properly formatted with actual newlines (not literal \\n strings)
+
+Repository Access
+~~~~~~~~~~~~~~~~~
+
+The trigger job accesses these Launchpad repositories:
+
+* `git+ssh://sjg1@git.launchpad.net/~sjg1/u-boot/+git/u-boot-concept-qemu`
+* `git+ssh://sjg1@git.launchpad.net/~sjg1/u-boot/+git/u-boot-concept-efi`
+
+Snap Store Distribution
+-----------------------
+
+Built packages are automatically published to Ubuntu Snap Store:
+
+* **u-boot-concept-qemu** - QEMU development builds
+* **u-boot-concept-efi** - EFI development builds
+
+Users can install these with::
+
+    snap install u-boot-concept-qemu --edge
+    snap install u-boot-concept-efi --edge
+
+Monitoring and Troubleshooting
+-------------------------------
+
+Build Status
+~~~~~~~~~~~~~
+
+* **GitLab CI**: Check pipeline status in GitLab interface
+* **Launchpad**: Monitor build progress at Launchpad project pages
+
+Common Issues
+~~~~~~~~~~~~~
+
+**SSH Authentication Failures**
+   - Verify `LAUNCHPAD_SSH_KEY` variable is set and protected
+   - Check SSH key has proper format with actual newlines
+   - Ensure key is associated with correct Launchpad account
+
+**Empty Commit Failures**
+   - Repository may have restrictions on empty commits
+   - Check Launchpad repository access permissions
+   - Verify SSH user matches repository owner
+
+**Build Failures**
+   - Check Launchpad build logs for specific errors
+   - Verify snap packaging configuration is correct
+   - Ensure source dependencies are available
+
+Security Considerations
+-----------------------
+
+* SSH private keys should always be stored as protected GitLab variables
+* Only protected branches (master) should trigger production builds
+* Access to concept repositories should be limited to authorized maintainers
+* Regular rotation of SSH keys is recommended
+
+Release Types Summary
+---------------------
+
+The concept release mechanism involves two types of releases:
+
+**1. Scheduled Version Releases**
+   - Formal version releases with tags (e.g., `2025.02`, `2025.04-rc1`)
+   - Triggered by scheduled pipelines only
+   - Updates official version numbers in Makefile
+   - Creates GitLab releases with tags
+
+**2. Concept Snap Builds**
+   - Development builds for testing and evaluation
+   - Triggered by any push to master branch
+   - Published to Ubuntu Snap Store as edge channel
+   - Independent of formal version releases
+
+Development and Testing
+-----------------------
+
+For testing the trigger mechanism:
+
+1. Change trigger condition to test branch in `.gitlab-ci.yml`
+2. Temporarily remove "Protected" flag from `LAUNCHPAD_SSH_KEY` 
+3. Push to test branch with CI variable overrides to skip other stages
+4. Restore production configuration after testing
+
+Example test push::
+
+    git push -o ci.variable=TEST_SUITES=0 -o ci.variable=WORLD_BUILD=0 \\
+             -o ci.variable=TEST_PY=0 -o ci.variable=SJG_LAB=0 origin HEAD:try
\ No newline at end of file
diff --git a/doc/develop/concept_releases.rst b/doc/develop/concept_releases.rst
new file mode 100644
index 00000000000..500f3d37151
--- /dev/null
+++ b/doc/develop/concept_releases.rst
@@ -0,0 +1,52 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+U-Boot Concept Releases
+=======================
+
+This document tracks all concept releases of U-Boot, including both final
+releases and release candidates.
+
+About Concept Releases
+----------------------
+
+Concept releases are automated builds of U-Boot that are:
+
+* **Automatically generated** when changes are pushed to the master branch
+* **Published as snap packages** for easy installation and testing  
+* **Available in two variants**: QEMU-based and EFI-based builds
+* **Distributed through Ubuntu Snap Store** on the edge channel
+
+These releases allow developers and users to easily test the latest U-Boot
+features without building from source.
+
+Installation
+~~~~~~~~~~~~
+
+Install concept releases using snap::
+
+    snap install u-boot-concept-qemu --edge
+    snap install u-boot-concept-efi --edge
+
+Next Release
+------------
+
+The next final release is scheduled for **2025.10**
+on Monday, October 06, 2025.
+
+Release candidate schedule:
+
+* **2025.10-rc3**: Mon 25-Aug-2025
+* **2025.10-rc2**: Mon 08-Sep-2025
+* **2025.10-rc1**: Mon 22-Sep-2025
+* **2025.10** (Final): Mon 06-Oct-2025
+
+Release History
+---------------
+
+**2025.10-rc2** - Release Candidate
+   :Date: 2025-09-11
+   :Commit: 0447d5f5f59c7f3ab3a158ae25ad484aad24b75e
+   :Subject: Version 2025.10-rc2 release
+
+*Releases will be automatically added here by the CI system when version*
+*bumps occur.*
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 12a71b5b23a..1a8e0168c67 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -18,6 +18,8 @@ General
    patman
    process
    release_cycle
+   concept_cycle
+   concept_releases
    security
    sending_patches
    system_configuration