Skip to content

Latest commit

 

History

History
193 lines (130 loc) · 6.53 KB

MAINTAINERS.rst

File metadata and controls

193 lines (130 loc) · 6.53 KB
Raw

Notes for maintainers.

Pre-release test plan

  1. If no release branch exists, fork the version numbers in the release branch (vX.Y-branch) and the main branch. See "Cutting a release branch", below, for details.

    The rest of these steps should be done in the release branch:

    git checkout vX.Y-branch

  2. Make tox happy on the following first-party non-Linux platforms:

    • Windows 10
    • the latest macOS

    Do this by hand and check for any anomalous warnings in the output. Do not just trust CI.

  3. Make tox happy on other popular Linux distributions:

    • Arch
    • the latest Ubuntu LTS release
    • the latest Ubuntu development release
    • Debian stable
    • Debian testing
    • the latest Fedora release
    • the latest Fedora rawhide release

    Automated infrastructure for doing this in docker is in the docker-testing directory. Start by updating the Dockerfiles and compose.yaml in that directory if any newer distribution versions should be tested.

    Then, install docker compose in your host Linux environment and run:

    cd docker-testing
./run-tests.sh

    Make sure to check the tox.log files mentioned in the output for any anomalous warnings.

  4. Build alpha N (N=1 to start, then N=2 if you need more commits, etc.) and upload to pypi. See "Building and uploading the release wheels" below for a procedure.

  5. Install the alpha on test platforms.

    pip3 install west==X.YaN

  6. Create and update a default (Zephyr) workspace on all of the platforms from 1., using the installed alpha:

    west init zephyrproject
cd zephyrproject
west update

    Make sure zephyrproject/zephyr has a branch checked out that matches the default branch used by zephyr itself.

  7. Do the following Zephyr specific testing in the Zephyr workspace on all of the platforms from 1. Skip QEMU tests on non-Linux platforms, and make sure ZEPHYR_BASE is unset in the calling environment.

    west build -b qemu_x86 -s zephyr/samples/hello_world -d build-qemu-x86
west build -d build-qemu-x86 -t run

west build -b qemu_cortex_m3 -s zephyr/samples/hello_world -d build-qemu-m3
west build -d build-qemu-m3 -t run

# This example uses a Nordic board. Do this for as many boards
# as you have access to / volunteers for.
west build -b nrf52dk_nrf52832 -s zephyr/samples/hello_world -d build-nrf52
west flash -d build-nrf52
west debug -d build-nrf52
west debugserver -d build-nrf52
west attach -d build-nrf52

    (It's still a pass if west build requires --pristine.)

  8. Assuming that all went well (if it didn't, go fix it and repeat):

    • update version in pyproject.toml to 'X.Y.Z' (i.e. drop the 'aN' suffix that denotes alpha N)
    • tag the release on GitHub (see "Tagging the release" for a procedure)
    • create a release on GitHub from the new tag by going to https://github.com/zephyrproject-rtos/west/releases clicking "Draft a new release", and following instructions
    • upload the release artifacts to PyPI (see "Building and uploading the release wheels" for a procedure)

  9. Send email to the Zephyr lists, announce@ and users@, notifying them of the new release. Include 'git shortlog' data of the new commits since the last release to give credit to all contributors.

Building and uploading the release wheels

Creating Pypi releases is done automatically from Github. After publishing a release on Github a release build is packaged and uploaded with the version specified in pyproject.toml.

To do these steps manually, you need the zephyr-project PyPI credentials for the 'twine upload' command.

git clean -ffdx
pip3 install --upgrade build twine
python -m build
twine upload -u zephyr-project dist/*

The 'git clean' step is important. We've anecdotally observed broken wheels being generated from dirty repositories.

Check out [packaging.python.org](https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives) for more detailed instructions.

Tagging the release

Create and push a GPG signed tag.

git tag -a -s vX.Y.Z -m 'West vX.Y.Z

Signed-off-by: Your Name <[email protected]>'

git push origin vX.Y.Z

Cutting a release branch

This is how to cut a new release branch for minor version vX.Y.

Summary of what happens:

  • before:
    • vX.Y-branch does not exist
    • main branch is at version X.(Y-1).99
  • after:
    • vX.Y-branch exists and is at version X.Y.0a1
    • main is at version X.Y.99
    • west.manifest.SCHEMA_VERSION may be updated

  1. Check the git logs since the last release:

    git log vX.(Y-1).99..origin/main

    Decide if west.manifest.SCHEMA_VERSION needs an update:

    • SCHEMA_VERSION should be updated to X.Y if release vX.Y will have manifest syntax changes that earlier versions of west cannot parse.
    • SCHEMA_VERSION should not be changed for west vX.Y if the manifest syntax is fully compatible with what west vX.(Y-1) can handle.

    If you want to change SCHEMA_VERSION, send this as a pull request to the main branch and get it reviewed and merged. (This requires a PR and review even though the rest of the steps don't.)

    Don't introduce incompatible manifest changes in patch versions. That violates semantic versioning. Example: if v0.7.3 can parse a manifest, v0.7.2 should be able to parse it, too, and with the same results.

  2. Create and push the release branch for minor version vX.Y.0, which is named "vX.Y-branch":

    git checkout -b vX.Y-branch origin/main
git push origin vX.Y-branch

    This should already contain the SCHEMA_VERSION change if one is needed.

    Subsequent fixes for patch versions vX.Y.Z should go to vX.Y-branch after being backported from main (or the other way around in case of an urgent hotfix).

  3. In vX.Y-branch, in src/west/version.py, set __version__ to X.Y.0a1. Push this to origin/vX.Y-branch. You don't need a PR for this.

  4. In the main branch, set version in pyproject.toml to X.Y.99. Push this to origin/main. You don't need a PR for this.

  5. Create an annotated tag vX.Y.99 which points to the main branch commit you just created in the previous step. Push it to origin/main. You don't need a PR for this. See refs/tags/v0.12.99 for an example. (This makes 'git describe' output easy to read during development.)

From this point forward, the main branch is moving independently from the release branch. Do the release prep work in the release branch.