CPU - The next-generation EESSI build-and-deploy bot

CPU is the next-generation EESSI build-and-deploy bot. It tries to achieve three main objectives:

• refactor the design of the first-generation EESSI build-and-deploy bot towards a unified, multi-threaded and customizable architecture,
• prepare for more security-focused scenarios, so it can be employed by a wide range of users and establish higher trust on what it builds, and
• improve user-friendliness concerning installation, configuration and monitoring.

Below, you find information on how to set up the build environment, test changes and create a new release.

Installation with local tagging

Set up development environment

Steps to perform once

# clone repo
git clone git@github.com:trz42/cpu.git
python3 -m vtestcpu
source vtestcpu/bin/activate
python3 -m pip install --upgrade pip

Tagging and installing a version

# if venv not activated yet
source vtestcpu/bin/activate
cd cpu
git tag v0.0.1-alpha
git tag
pip3 install -e ".[dev]"

Testing the installed version

pip show cpu
python -c "import cpu; print(cpu.__version__)"

If the last command fails, try

python -c "from importlib.metadata import version; print(version('cpu'))"

Debugging tags

git describe --tags
git log --oneline --decorate

After a change: re-tag and re-install

git tag -d v0.0.1-alpha   # Delete old tag
git tag v0.0.1-alpha      # Tag current commit
pip install -e ".[dev]"   # Reinstall

Run unit tests

• Run all tests

  python3 -m venv ../vpytest
  python3 -m pip install --upgrade pip
  source ../vpytest/bin/activate
  pip3 install -e ".[dev]"
  pytest
  deactivate

Steps to prepare a release

1. Create branch for release from develop

   git checkout develop
   git pull
   git checkout -b release_vX.Y.Z origin/develop

2. Update CHANGELOG.md for the release using the template below

   [!NOTE] The format of the first line including two hashmarks, version in brackets is important for automatic creation of releases!

   ## [X.Y.Z] - 2025-11-15
   
   ### Added
   - Initial package structure
   - Basic package installation support
   - Version management with setuptools-scm
   
   ### Changed
   - none
   
   ### Fixed
   - none

3. Commit and push the changes

   git add CHANGELOG.md
   git commit -m "update CHANGELOG.md for release vX.Y.Z
   git push origin release_vX.Y.Z

4. Create PR on GitHub

   • Open https://github.com/trz42/cpu/pulls
   • Create a pull request to merge the updated CHANGELOG.md into the develop branch
   • Title: Updated CHANGELOG.md for release vX.Y.Z
   • Description: copy the contents of the CHANGELOG.md for this release

5. Get PR merged

   • After it got merged update local git repository

     git checkout develop
     git pull

   • Cleanup branch for release locally and remotely

     git branch -d release_vX.Y.Z
     git push origin :release_vX.Y.Z
     git branch -r

6. Create PR to merge develop into main

   • Open https://github.com/trz42/cpu/compare/main...develop
   • Click on "Create pull request" to start creating a new pull request
   • Title: Release vX.Y.Z
   • Description: contents of CHANGELOG.md for this release

7. Get PR merged

8. Checkout main, pull in changes, tag it and push tag to GitHub

   git checkout main
   git pull
   git tag
   git tag vX.Y.Z
   git push origin vX.Y.Z

   [!NOTE] See below for instructions to manually create the release including packages in case the CI fails.

9. Try to install locally from GitHub and run some tests

   python3 -m venv ../vtestinstall
   source ../vtestinstall/bin/activate
   python3 -m pip install --upgrade pip
   pip install https://github.com/trz42/cpu/releases/download/vX.Y.Z/cpu-X.Y.Z-py3-none-any.whl
   pip show cpu
   python -c "import cpu; print(cpu.__version__)"
   deactivate

   (Optionally) cleanup virtual environment: rm -rf ../vtestinstall

Creating release manually

If the step in which one pushes a tag to GitHub does not result in the automatic creation of a release, perform the following steps to create it manually.

1. Build package locally

   python3 -m venv ../vbuildcpu
   source ../vbuildcpu/bin/activate
   python3 -m pip install --upgrade pip
   pip install -e ".[dev]"
   python -m build
   ls dist
   deactivate

   (Optionally) cleanup virtual environment: rm -rf ../vbuildcpu

2. Create release on GitHub: use pushed tag, copy changelog and upload whl and tar.gz

   • Open https://github.com/trz42/cpu/releases/new
   • Select the release created above
   • Title: vX.Y.Z
   • Description: contents of CHANGELOG.md for this release
   • Upload cpu-X.Y.Z-py3-none-any.whl and cpu-X.Y.Z.tar.gz from dist directory

Logging

CPU uses Python's built-in logging with a custom TRACE level for detailed debugging.

Log Levels

• TRACE (5): Function entry/exit via decorators, very detailed flow
• DEBUG (10): Detailed diagnostic information
• INFO (20): Normal operational messages (default)
• WARNING (30): Unexpected but handled situations
• ERROR (40): Error conditions
• CRITICAL (50): System-level failures

Configuration

Configure logging in config.yaml:

bot:
  logging:
    level: INFO
    file: logs/cpu.log
    
    # Per-module overrides
    loggers:
      cpu.messaging: DEBUG
      cpu.components: INFO

See docs/logging.md for detailed logging guide.