OTA Connect Developer Guide

Release process

1. Update the changelog and other docs

This is normally a good time to update the changelog. Ideally, the changelog should be updated with the new release number before creating the release so that the packaged source code includes the correct information about the release. The easiest way to check the changelog is to review all PRs merged to master since the last release was made and to verify that any important changes that impact the user experience are reflected in the changelog.

There are a few additional documents that should be updated to refer to the new release:

  • The docs README contains a table with links to the doxygen docs for each release.

  • The garage-deploy installation guide contains a reference to the latest release of the garage-deploy Debian package.

2. Pull in any new changes from the current docs branch

The docs published as latest in the OTA Connect Developer Guide are built from the most recent release’s docs branch ({version}-docs). There will very likely be changes from there that have not been pulled into master yet. Open up a PR to merge the previous release’s docs into master, resolving any merge conflicts as needed. Once that PR is merged, you can move on to the next step.

3. Create a new tag

Releases are built automatically by gitlab from annotated tags of the form major.minor, where major and minor are numbers. We normally set major to the current year and minor to an incrementing number beginning at 1.

To create a release, checkout the revision you want to bless, then:

git tag -as <tag>   # e.g. git tag -a 2018.4
git push github <tag>

Gitlab will build this tag and automatically create a release for it on github.

3.1. Create a new docs branch

Create (and push to github) a new branch with the commit you just tagged as the parent:

git checkout -b <tag>-docs # e.g. git checkout -b 2019.63-docs
git push github <tag>-docs

4. Update doxygen on github

To update the doxygen documentation for master on github, you will need to do something like the following:

  1. In an aktualizr repo, run make doxygen (or make docs) in the build directory.

  2. Clone a second aktualizr repo and run git checkout gh-pages.

  3. In the second repo, run git rm search/* *.css *.html *.js *.png *.map *.md5 *.png *.svg.

  4. Copy the contents of <build_dir>/docs/doxygen/html into the root of the second repo. (Something like cp -a <build_dir>/docs/doxygen/html/* <second_repo>.)

  5. In the second repo, run git add ., git commit -as, and git push.

  6. Wait a minute or two for github to refresh and render the files.

5. Add doxygen pages for the new release on github

To add doxygen docs for a new tag, you will need to do something like the following:

  1. Check out the tag or commit you wish to add (git checkout 2018.63, for example).

  2. Clean out the build directory (to remove stale objects), then run CMake and doxygen again:

    rm -rf build/*
    cd build
    cmake ..
    make doxygen
  3. Clone a second aktualizr repo and run git checkout gh-pages.

  4. In the second repo, make a directory for the tag or commit you wish to add, i.e. mkdir 2018.63.

  5. Copy the contents of <build_dir>/docs/doxygen/html into the directory you just created. (Something like cp -a <build_dir>/docs/doxygen/html/* <second_repo>/2018.63.)

  6. In the second repo, run git add 2018.63, git commit -as, and git push.

  7. Wait a minute or two for github to refresh and render the files.

6. Update the description of the github release

Once the release is ready on github, it should be edited to include a link to the changelog and doxygen documentation for that particular release. You can use a previous release as a model of how to format these links.

7. Update the Uptane fork of aktualizr

Uptane has a fork of aktualizr in their namespace. It should be updated with the same version of aktualizr used to make the new release.

8. Update the homebrew recipe for aktualizr

The homebrew aktualizr recipe should be updated with the new release. You’ll need a mac, with homebrew installed, to do this.

  1. Edit the recipe on your local system with brew edit aktualizr, and replace the old version tag with the new one.

  2. Build it, and then bottle it:

    brew rm aktualizr && \
    brew install --build-bottle aktualizr && \
    brew bottle aktualizr

    This will create a bottle file named aktualizr--VERSION.mojave.bottle.tar.gz, and output a block of Ruby code that looks something like this:

      bottle do
        cellar :any
        sha256 "391bc242685d86fd4fc69d90d98e10a464e6feebca943d3f48f848615c898085" => :mojave
  3. Rename the file, removing one of the dashes (i.e. mv aktualizr--2019.6.mojave.bottle.tar.gz aktualizr-2019.6.mojave.bottle.tar.gz). I don’t know why the generated filename is always wrong, but it is.

  4. Add the renamed bottle file as an artifact to the release on the aktualizr releases page.

  5. Replace the bottle do block in your local recipe with the generated block from step 2, and add the appropriate root_url directive.

  6. Test the recipe locally, including installing from the bottle: brew reinstall --force-bottle aktualizr.

  7. Open a PR on the homebrew-otaconnect repo to update the recipe with all your changes.

9. Test the released Debian packages

Don’t forget to test the resulting Debian packages manually!