EM-Bright Release Instructions

This is a checklist meant to guide maintainers of the em-bright package through a release.

Once all the changes to be included in release have been pushed to main, we may begin following the instructions. An a general rule of thumb, the version number follows the convention X.Y.Z, where minor changes bump Z, i.e.: 1.0.0 -> 1.0.1, and major changes bump Y, i.e.: 1.0.1 -> 1.1.0.

Initial Checklist:

1. All CI pipelines on Gitlab pass. In our case, this includes unit tests, docs, dist, and lint.

2. The Changelog has been updated to reflect changes under the proper version number.

3. All major changes to code have been thoroughly reviewed and tested.

Next we tag the release:

1. Make sure we are on main

2. Update the links and tags in the __init__.py, pyproject.toml, and the unit tests. Be careful that package links do not point to the main branch, but instead to the version tag! Below is shown where to look for this in the __init__.py file:

   __version__ = 'X.Y.Z'
   
   PACKAGE_DATA_BASE_URL = (
       'https://git.ligo.org/emfollow/em-properties/em-bright/'
       f'-/raw/v{__version__}/ligo/em_bright/data'
   )
   

3. Commit the changes:

   git commit .
   

4. Tag the release:

   git tag -a vX.Y.Z -m "version X.Y.Z"
   

5. Push the changes:

   git push && git push --tags
   

Then we get ready to build and publish the package:

1. Clear the dist folder:

   rm -rf dist
   

2. Build the package:

   poetry build
   

3. Now, it is good practice to first upload to testpypi to ensure things go smoothly:

   poetry publish -r testpypi --username {your_username} --password {your_password}
   

4. Once uploading to testpypi has succeeded, upload to pypi. This cannot be undone:

   poetry publish --username {your_username} --password {your_password}
   

Finally, we update the Changelog and prepare the repo for further work:

1. Update the Changelog, following the established convention:

   ## [{New X.Y.Z version number}] - Unreleased
   
   - No changes yet
   

2. Commit the changes, it is okay to skip the CI here:

   git commit -m "Back to development [skip-ci]"
   

3. Push the updated Changelog:

   git push
   

Now that the release is completed, there are two more tasks to take care of:

1. Update the dependencies in places where em-bright is used in production, like gwcelery. Simply restrict the em-bright dependency of gwcelery to the new and released version.

2. Make a SCCB request, in the form of a gitlab issue. Follow the template provided, and feel free to reference previous em-bright requests.