ReleaseEngineering/How To/Update RelengAPI
RelengAPI is composed of a bunch of different Python distributions. You can see the current versions at https://api.pub.build.mozilla.org/versions.
So, how do you update one of those?
Cautions
Will your change
- require a DB change
- If so, consider carefully whether the DB change or the code change need to be landed first.
- make an incompatible API change
- If so, you should endeavor to make it non-incompatible, and otherwise announce the change to any users beforehand.
Shipping It
Figure out the next version number based on semantic versioning. Run `misc/release.sh x.y.z`. This will open an editor to edit the release notes. Have a look at the merges included and summarize them. Try to include context ("retry database operations" doesn't say *which* database operations are retried) and pull request numbers. See the 2.1.0 notes for a good example.
After tagging and pushing, upload the resulting tarball (in `dist/`) to relengapi:
scp dist/relengapi-mapper-2.3.4.tar.gz <your user>@relengwebadm.private.scl3.mozilla.com:/tmp
and put it in place on relengwebadm as root
mv /tmp/relengapi-mapper-2.3.4.tar.gz /mnt/netapp/relengweb/pypi/pub
Please note the files will still be owned by your user, so you should make it universally readable:
chmod a+r /mnt/netapp/relengweb/pypi/pub/relengapi-mapper-2.3.4.tar.gz
Also on relengwebadm, cd to the source directory for staging or production
cd /data/releng-stage/src/relengapi cd /data/releng/src/relengapi
and edit requirements.txt to specify the new version.
Now, if you're ready to ship the change live with no DB updates or settings changes:
./update
This will upgrade the packages, build the docs, and deploy to the webheads.
If you need to do some DB migrations or the like first:
./update -n
which will skip the deployment step. Then update the DB schema (assuming the schema upgrade won't break the currently-deployed code from the previous release):
./relengapi.sh alembic relengapi upgrade
(or whatever changes you need to make before deploying the code). Finally, deploy the new code with
./update
In some cases, you'll want to deploy the new code *before* the schema upgrade, in which case, just reverse those steps.