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