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)
This commit is contained in:
GitLab CI Runner
200
doc/develop/concept_cycle.rst
Normal file
200
doc/develop/concept_cycle.rst
Normal file
@@ -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
|
||||
52
doc/develop/concept_releases.rst
Normal file
52
doc/develop/concept_releases.rst
Normal file
@@ -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.*
|
||||
@@ -18,6 +18,8 @@ General
|
||||
patman
|
||||
process
|
||||
release_cycle
|
||||
concept_cycle
|
||||
concept_releases
|
||||
security
|
||||
sending_patches
|
||||
system_configuration
|
||||
|
||||
Reference in New Issue
Block a user