d5ba460e73
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)
200 lines
6.4 KiB
ReStructuredText
200 lines
6.4 KiB
ReStructuredText
.. 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 |