Skip to content

Fixes GitHub workflow generating documentation from release artifacts#2506

Merged
jburel merged 4 commits into
ome:developfrom
sbesson:autogen_fixes
Dec 11, 2025
Merged

Fixes GitHub workflow generating documentation from release artifacts#2506
jburel merged 4 commits into
ome:developfrom
sbesson:autogen_fixes

Conversation

@sbesson

@sbesson sbesson commented Dec 4, 2025

Copy link
Copy Markdown
Member

This effort was primarily motivated to propagate some of the property changes associated with the OMERO.web 5.30.0 release to the OMERO documentation.

A few issues were found as part of an initial investigation:

  • the auto-generation workflow has been broken for several months with Changes from upstream repositories: openmicroscopy #2500 being the latest open PR and many failing actions
  • the omero config parse command is skipped in autogen_openmicroscopy.sh and several configuration properties are out-of-sync
  • the workflow builds OMERO.server from source which has two downsides:
    • it increases significantly build times
    • it includes changes from merged but unreleased upstream changes into PRs against the reference documentation
  • several recent builds failed in autogen_db_version.py with an error of type packaging.version.InvalidVersion: Invalid version: '4.3__0'
  • the create-pull-request action failed on my fork and is behind

To address all of the above, the following changes are proposed:

  • OMERO.server is no longer built from source but the latest GitHub release asset is downloaded using gh release download, similarly to the OMERO.py GitHub workflow. The SUFFIX and BUILD variables are removed or disabled.
  • autogen_db_version.py is updated to only detect SQL files and folders corresponding to release versions of the OMERO database i.e. under the form <MAJOR>.<MINOR>__<PATCH>, excluding historical schema versions as well as all intermediate DEV database versions. The usage of packaging.version is dropped in favour of the get_mmap()
  • the peter-evans/create-pull-request action is updated to v7 and uses GITHUB_TOKEN under the hood

Note this workflow is currently configured to run in a cron matter making changes hard to evaluate. As a proof of concept, sbesson#8 was generated by https://github.com/sbesson/omero-documentation/actions/runs/19940358557 which includes an extra commit on top of this branch to force the workflow and a build time <2min

The current logic builds OMERO.server from source which has several
downsides including pulling artifacts from OME artifactory on every
build and trying to generate documentation from unreleased content.
Using gh release download with the GH token should considerably
speed up build times
@sbesson
sbesson requested review from jburel and knabar December 4, 2025 18:54
git clone https://github.com/ome/omeroweb-install
git clone https://github.com/ome/omero-install
- name: Build OMERO.server
- name: Download latest release of OMERO.server

@jburel jburel Dec 4, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This means that the configuration changes will only be included in the documentation after a release of the OMERO.server and not when PRs are merged.
This means that as we have seen previously the configuration text might be incorrect or not correctly displayed. We will not be able to catch that. This is probably okay to pay that cost since we are also reducing the build time significantly

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, for simple changes like typos/descriptions, the generation step creates a bit of unnecessary friction as you might need to wait until the next release.

On the other side:

  • the generation of the configuration properties page has been turned off in ba0ee84 for more than a year. So reenabling those is an improvement
  • building OMERO.server from source across these repositories is currently not a viable option. We'll need to look into this issue separately as it is currently failing the builds on ome/openmicroscopy and blocking the release workflow of OMERO.server.

@jburel
jburel merged commit fb0193e into ome:develop Dec 11, 2025
1 check passed
@sbesson
sbesson deleted the autogen_fixes branch December 11, 2025 09:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants