U-Boot

.. 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