diff --git a/docs/bioformats-release-process.rst b/docs/bioformats-release-process.rst new file mode 100644 index 0000000..3808d57 --- /dev/null +++ b/docs/bioformats-release-process.rst @@ -0,0 +1,257 @@ +BioFormats release +================== + +.. _Bio-Formats: https://github.com/ome/bioformats +.. _Bio-Formats Documentation: https://github.com/ome/bio-formats-documentation +.. _Bio-Formats Downloads: https://downloads.openmicroscopy.org/bio-formats/ +.. _Octave Docker: https://github.com/ome/bio-formats-octave-docker +.. _Read The Docs: https://readthedocs.org/projects/bio-formats/builds/ +.. _Data Repository: https://github.com/openmicroscopy/data_repo_config +.. _Bio-Formats homebrew: https://github.com/ome/homebrew-alt + +This document describes the release process of the `Bio-Formats`_ Java library. +The release process uses GitHub actions, make sure that the actions are active before pushing any tag. + +Before starting the release process, +open a Pull Request with a new release entry in the `whats-new `_ page. When approved by both the OME team and the Glencoe Software team, merge and start the release process. + + +Release process +^^^^^^^^^^^^^^^ + +Source code release +------------------- + +Before making a new release, merge all contributions on the ``develop`` branch of `Bio-Formats`_. + +The first operation to perform a Maven release is to bump the version out of +``SNAPSHOT`` using the Maven versions plugin, add and commit:: + + $ mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ mvn versions:set-property -Dproperty=release.version -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ git add -u . + $ git commit -m "Bump release version to x.y.z" + + +A signed tag must be created for the released version using :command:`git tag -s`:: + + $ git tag -s -m "Tag version x.y.z" vx.y.z + + +Revert to ``SNAPSHOT``, add and commit:: + + $ mvn versions:set -DnewVersion=x.y.t-SNAPSHOT -DgenerateBackupPoms=false + $ mvn versions:set-property -Dproperty=release.version -DnewVersion=x.y.z-SNAPSHOT -DgenerateBackupPoms=false + $ git add -u . + $ git commit -m "Revert to snapshot" + +Both the ``develop`` branch as well as the tag must be pushed upstream:: + + $ git push origin develop vx.y.z + +This will trigger GitHub action builds, generate artifacts, create a GitHub release and upload +the artifacts to the release on GitHub and to the `OME artifactory`_. +An hourly cron job runs on our virtual machine and copy the artifacts published on Github under `Bio-Formats Downloads`_. + +Close the milestone if any and add new one if needed. + + +Testing the artifacts +--------------------- + +To test the artifacts published, + - Test the `bio-formats-command-line-tools `_. + - Test `MATLAB (only) `_. + - Test `Fiji Plugin `_ + - Check the schema version using the command line tools:: + $ ./bfconvert B.ome.tiff + $ ./tiffcomment B.ome.tiff + Check that the schema version in OME-XML be ``2016-06`` + + +If an error occurs during the testing: + - Delete the release and the tag on GitHub. + - Delete the artifacts on `OME artifactory`_. + - Delete the folder corresponding to the latest release under `Bio-Formats Downloads`_, if it has already been created. + +Bio-Formats examples release +---------------------------- + +Before making a release, merge all contributions on the ``master`` branch of `Bio-Formats Examples `_. + +The first operation to perform a Maven release is to bump the version out of +``SNAPSHOT`` using the Maven versions plugin:: + + $ mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ mvn versions:set-property -Dproperty=formats-gpl.version -DnewVersion=x.y.z -DgenerateBackupPoms=false + +Bump the ``version`` and ``formats-gpl`` in :file:`build.gradle`. + +Add and commit:: + + $ git add -u . + $ git commit -m "Bump release version to x.y.z" + + +A signed tag must be created for the released version using :command:`git tag -s`:: + + $ git tag -s -m "Tag version x.y.z" vx.y.z + +Revert to ``SNAPSHOT`` in :file:`pom.xml`:: + + $ mvn versions:set -DnewVersion=x.y.t-SNAPSHOT -DgenerateBackupPoms=false + +Revert the ``version`` to ``SNAPSHOT`` in :file:`build.gradle`. + +Both the ``master`` branch as well as the tag must be pushed upstream:: + + $ git push origin master vx.y.z + +This will trigger GitHub action builds, generate artifacts and upload +the artifacts to the `OME artifactory`_. + + +Documentation release +--------------------- + +Before making a new release, merge all contributions on the ``master`` branch of `Bio-Formats Documentation`_. + +The first operation to perform a Maven release is to bump the version out of +``SNAPSHOT`` using the Maven versions plugin, add and commit:: + + $ mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ mvn versions:set-property -Dproperty=bioformats.version -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ mvn versions:set-property -Dproperty=bio-formats-examples.version -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ git add -u . + $ git commit -m "Bump release version to x.y.z" + +A signed tag must be created for the released version using :command:`git tag -s`:: + + $ git tag -s -m "Tag version x.y.z" vx.y.z + +Revert to ``SNAPSHOT``, add and commit:: + + $ mvn versions:set -DnewVersion=x.y.t-SNAPSHOT -DgenerateBackupPoms=false + $ git add -u . + $ git commit -m "Revert to snapshot" + +Both the ``master`` branch as well as the tag must be pushed upstream:: + + $ git push origin master vx.y.z + + +The documentation is built and published on `Read The Docs`_. + +An hourly cron job runs on our virtual machine and adds redirect from for example `docs.openmicroscopy.org/bio-formats/7.3.1 `_ to `bio-formats.readthedocs.io/en/v7.3.1/ `_. + +Close the milestone if any and add new one if needed. + +Fiji Update site +---------------- + +Before making a release, merge all contributions on the ``master`` branch of `Bio-Formats Fiji `_. + +The first operation to perform a Maven release is to bump the version out of +``SNAPSHOT`` using the Maven versions plugin, add and commit:: + + $ mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ mvn versions:set-property -Dproperty=bioformats.version -DnewVersion=x.y.z -DgenerateBackupPoms=false + $ git add -u . + $ git commit -m "Bump release version to x.y.z" + $ git push origin master + $ mvn clean package -Dfiji.home=x.y.z + +`Upload `_ the generated jars to the update site. + + +Revert to ``SNAPSHOT``, add, commit and push to origin:: + + $ mvn versions:set -DnewVersion=x.y.t-SNAPSHOT -DgenerateBackupPoms=false + $ git add -u . + $ git commit -m "Revert to snapshot" + $ git push origin master + +Homebrew +-------- + +Before making a new release, merge all contributions on the `master` branch (rare) of `Bio-Formats homebrew`_. + +- Update the `Bio-Formats formula `_ + by pointing to the ``bioformats-RELEASE.zip`` and update the ``sha256`` value. The ``sha256`` can be found in the ``SHASUM`` file under https://downloads.openmicroscopy.org/bio-formats/RELEASE/artifacts/. +- Update the version and sha256 in the ``.rb`` file corresponding to the current release. + + +Add, commit the changes and push to origin:: + + $ git add -u . + $ git commit -m "Bump release version to x.y.z" + $ git push origin master + + +Docker container release +------------------------ + +Before making a new release, merge all contributions on the `master` branch (rare) of `Octave Docker`_. + +When the artifacts are available under `Bio-Formats Downloads`_, you can release the `Octave Docker`_. +Bump the version in `Dockerfile `_ to the latest release version. + +Add, commit the changes and push to origin:: + + $ git add -u . + $ git commit -m "Bump release version to x.y.z" + $ git push origin master + +Close the milestone if any and add new one if needed. + + +Data repository release +----------------------- + +Before making a new release, merge all contributions on the `master` branch of `Data Repository`_. + +A signed tag must be created for the released version using :command:`git tag -s`:: + + $ git tag -s -m "Tag version x.y.z" vx.y.z + $ git push origin master + + +Website release +--------------- + +When the documentation is deployed, you can make a release of the `Open Microscopy Environment`_ website. + +To make a release: + - Update the version in `_config.yml `_ + - Add a new entry under `_posts `_. The name of the post should be ``YYYY-MM-DD-omero-MAJOR-MINOR-PATCH.md`` e.g. ``2024-08-15-omero-5-6-13.md`` + - Point to the post announcing the release in `bio-formats/downloads/index.html `_. + - Add, in alphabetical order, new contributors to `_data/bio-formats.json `_ and `_data/contributors.json `_. + +A signed tag must be created using :command:`git tag -s`:: + + $ git tag -s -m "Message" YYYY.MM.DD + +Before pushing, make sure that the documentation has been built and published on `Read The Docs`_. +Both the `master` branch as well as the tag must be pushed upstream:: + + $ git push origin master YYYY.MM.DD + +An hourly cron job runs on our virtual machine and deploys the website. + + +Announcement +------------ + + - Announce the release on `image.sc`_ using the ``Announcements`` category after checking that the website has been deployed. + - Announce on the Confocal email + - Announce on X and linkedin + + +Post Release +------------ + + - Add an entry in `Web Server Stats`_. + - Bump Bio-Formats version in `omero-model `_. + - Bump Bio-Formats version in `OMEZarrReader `_. + - Bump Bio-Formats version in `pom-scijava `_. + diff --git a/docs/components-release.rst b/docs/components-release.rst index 4a9a474..8315685 100644 --- a/docs/components-release.rst +++ b/docs/components-release.rst @@ -8,6 +8,7 @@ Note this is not an exhaustive list of all tools release process. .. toctree:: :maxdepth: 1 + bioformats-release-process cpp-development gradle-development java-development diff --git a/docs/conf.py b/docs/conf.py index 0cc517f..fb4e42e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -171,6 +171,7 @@ .. _Conda: https://docs.conda.io/en/latest/ .. _PyTables: http://pytables.org .. _image.sc: https://forum.image.sc/ +.. _Web Server Stats: https://docs.google.com/spreadsheets/d/1K7ab1UpuiE3FmAq3et7OpyxFwumrT7z8tGrDDBSDxsk/edit#gid=908994883 .. |SSH| replace:: :abbr:`SSH (Secure Shell)` .. |VM| replace:: :abbr:`VM (Virtual Machine)`