Proposal for automating checking for API changes, preparing release branches

This is a proposal for automating 2 tasks in LALSuite:

• Checking for API changes. We currently rely on people manually ticking a box in the MR template, which is bound to give inconsistent results. We also have lint:api CI jobs, but these must be manually inspected, and currently only check the C library API.
• Preparing a release branch. Currently this involves Adam manually cherry-picking commits listed in an release request issue onto a branch. I assume this would also involve manually checking for API changes, or relying on the lint:api jobs.

The proposal is as follows:

• There will be a permanent release branch on https://git.ligo.org/lscsoft/lalsuite/, instead of the current dated release-YYYYMMDD branches.
• To add commits to a release, developers will follow a 2-step process:
  • Create a MR to merge the changes into the main master branch.
  • Once merged into master, create a 2nd MR to cherry-pick the changes onto release. At this time, the CI would check the API e.g. for any backward-incompatible changes.
• Once the release branch has been populated with the required commits, an release request issue is opened requesting a release off the release branch. Since all the cherry-picking and API-checking has already happened, making the release would be just a matter of updating version numbers based on the latest lint:api job results from the release branch. (This step could potentially also be automated in future.)
• For backward-incompatible releases, one would open a release request issue requesting a release off master. If accepted, this would involve manually merging master into release (which only a maintainer could do), bypassing the CI checks from the 2-step process above. Pushing the release branch would then run the lint:api jobs to check the API changes, and the rest of the release process would proceed as above.

The API checks performed in the lint:api jobs would also be expanded to cover, as well as the C libraries:

• the Python interface, using a package I wrote called py-api-dumper
• existence of application binaries, e.g. removing an application binary would be a major API change

We would rely on the lint:api jobs to correctly check for API changes, rather than asking users to do so:

• The current API tick boxes in the MR template would be removed.
• Instead the LALSuite robot would use the output of the lint:api jobs to apply the apinone / apiminor / apimajor labels.

While there would be restrictions on what API changes are allowed to be cherry-picked onto the release branch, in contrast the master branch would not have any restrictions on API changes (either through the CI, or implied by practise). This will give flexibility to developers to push changes to master that break the API (e.g. cleaning up old code), with the provision that such changes may take some time to make their way into a release.

Some common workflow scenarios for developers:

1. I have an API backward-compatible change. I would like to get a point release including it.
   1. Merge the change into master.
   2. Open MR to cherry-pick the change from master to release; at this point the API would be checked to ensure it really is a backward-compatible change.
   3. Once merged onto release, open a release request issue for a release off release.
2. I have an API backward-incompatible change. I need to get it released.
   1. Merge the change into master.
   2. Open a release request issue for a release off master.
3. I have an API backward-incompatible change. I don't need it to be released straight away.
   1. Just merge the change into master.