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?

Note: These instructions are for update only. For restarts, contact #moc

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.

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.

Note: ./update regenerates the virtualenv from a high level requirement.txt - even if that doesn't change, dependencies can be upgraded at any time, and may lead to breakage. It is recommended that you **always** deploy and test on staging immediately before attempting a production update.

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.