Skip to content

DM-48010: Add directions to playbook for Science Pipelines quick-builds #242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 29, 2025
Merged

DM-48010: Add directions to playbook for Science Pipelines quick-builds #242

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d6bb84a
Add directions to playbook for science pipelines quick-builds
eigerx May 29, 2025
0b0c977
Playbook edits for formatting and clarity; mostly Release Management …
eigerx May 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 66 additions & 46 deletions doc/playbook.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,17 +22,21 @@ Containers
==========

The service consists of two containers.
The first is a base container with the Science Pipelines "stack" code and networking utilities.
The second is a service container made from the base that has the Prompt Processing service code.
The first is a **base container** with the Science Pipelines "stack" code and networking utilities.
The second is a **service container** made from the base that has the Prompt Processing service code.
All containers are managed by `GitHub Container Registry <https://github.com/orgs/lsst-dm/packages?repo_name=prompt_processing>`_ and are built using GitHub Actions.

To build the base container:

* If there are changes to the container, push them to a branch, then open a PR.
The container should be built automatically.
* If there are no changes (typically because you want to use an updated Science Pipelines container), go to the repository's `Actions tab <https://github.com/lsst-dm/prompt_processing/actions/workflows/build-base.yml>`_ and select "Run workflow".
From the dropdown, select the branch whose container definition will be used, and the label of the Science Pipelines container.
* New containers built from ``main`` are tagged with the corresponding Science Pipelines release (plus ``w_latest`` or ``d_latest`` if the release was requested by that name).
This will build the container automatically.
* If there are no changes (typically because you want to use an updated Science Pipelines container), go to the repository's `Actions tab <https://github.com/lsst-dm/prompt_processing/actions/workflows/build-base.yml>`_ and select "**Run workflow**". From the dropdown menu, select:

#. The branch whose container definition will be used
#. The label of the Science Pipelines container.
Copy link
Member

@kfindeisen kfindeisen Dec 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I think you need to include an entry for the science pipelines container (possibly adding it on commit "Add directions to playbook..."?) AFAICT that's the step you and Erin missed over the weekend.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Huh. [Sadly I was mostly out that weekend so I'll check in with @erinleighh about the specifics]. Do you mean that this set of directions needs the step where the container label is taken from the appropriate container at this link: https://github.com/orgs/lsst-dm/packages?repo_name=prompt_processing ?

Copy link
Member

@kfindeisen kfindeisen Dec 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

No, the action is hardcoded to always build prompt-base, and the container label goes under "Science Pipelines tag" as usual.

But the "Science Pipelines container" needs to have the name of the input container being used to make the base -- lsstsqre/centos, the default, is the official weekly/daily Science Pipelines build, while Quick-Stack is ghcr.io/lsst/quick-stack (you mentioned it below, as the output of the build process).

#. If using a quick-stack build, the Science Pipelines Container should be set to `ghcr.io/lsst/quick-stack <https://ghcr.io/lsst/quick-stack>`_.

New containers built from ``main`` are tagged with the corresponding Science Pipelines release (plus ``w_latest`` or ``d_latest`` if the release was requested by that name).
For automatic ``main`` builds, or if the corresponding box in the manual build is checked, the new container also has the ``latest`` label.
Containers built from a branch use the same scheme, but prefixed by the ticket number or, for user branches, the branch topic.

Expand All @@ -45,8 +49,8 @@ To build the base container:
To build the service container:

* If there are changes to the service, push them to a branch, then open a PR.
The container should be built automatically using the ``latest`` base container.
* To force a rebuild manually, go to the repository's `Actions tab <https://github.com/lsst-dm/prompt_processing/actions/workflows/build-service.yml>`_ and select "Run workflow".
This will build the container automatically using the ``latest`` base container.
* To force a rebuild manually, go to the repository's `Actions tab <https://github.com/lsst-dm/prompt_processing/actions/workflows/build-service.yml>`_ and select "**Run workflow**".
From the dropdown, select the branch whose code should be built.
The container will be built using the ``latest`` base container, even if there is a branch build of the base.
* To use a base other than ``latest``, edit ``.github/workflows/_matrix-gen.yaml`` on the branch and override the ``BASE_TAG_LIST`` variable.
Expand All @@ -68,6 +72,12 @@ Any subsequent builds of the service container will build against both bases.

This is the only situation in which a change to ``BASE_TAG_LIST`` should be committed to ``main``.

It will sometimes be necessary to compile a container with the LSST Science Pipelines manually (called a Quick-Stack build).
Copy link
Member

Choose a reason for hiding this comment

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

This commit largely reverses "Add directions to playbook for Science Pipelines quick-builds ". Would it be possible to merge the two so that the commit history looks more coherent?

Copy link
Member

Choose a reason for hiding this comment

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

I meant merge only those two commits; now it's impossible to tell the formatting changes from the content ones.

Generally, this only occurs if the intended daily or weekly stack does not compile.
In these cases, the Science Pipelines themselves must be built ahead of the base container.
Instructions for building the Science Pipelines are `here <https://github.com/lsst/gha_build/blob/main/README.md>`_.
Copy link
Member

Choose a reason for hiding this comment

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

Mention that, for PP, we only need to build lsst_distrib?

For Prompt Processing, we only need to build ``lsst_distrib``.

Release Management
==================

Expand All @@ -79,48 +89,63 @@ From the ``main`` branch you can release a new major version (``X.0.0``), a new
Release tags are semantic version identifiers following the `pep 440 <https://peps.python.org/pep-0440/>`_ specification.
Please note that the tag does not include a ``v`` at the beginning.

1. Choose Version Number
#. Choosing the Version Number

The first step in making a release is choosing an appropriate version number to describe it. This subsection offers guidance on this choice, as well as on differentiating between major and minor releases.

**To see which changes have occurred since the last release:**

On GitHub.com, navigate to the main page of the repository.
To the right of the list of files, click the latest release.
At the top of the page, click **## commits to main since this release**.
(If there's no such link or it doesn't mention ``main``, the release is probably based off a branch; go up to Releases and try older versions until you find one.)
This is the list of internal changes that will be included in the next release.

On GitHub.com, navigate to the main page of the repository.
To the right of the list of files, click the latest release.
At the top of the page, click **## commits to main since this release**.
(If there's no such link or it doesn't mention ``main``, the release is probably based off a branch; go up to Releases and try older versions until you find one.)
This is the list of internal changes that will be included in the next release.
If you are planning to update the Science Pipelines tag, you should also check the `Science Pipelines changelog <https://lsst-dm.github.io/lsst_git_changelog/weekly/>`_.
In practice, almost any Science Pipelines update is at least a minor version, because new features are added constantly.
You may need to do a "Quick-Stack" build, or build the science pipelines manually. This would justify a patch version of Prompt Processing.

If you are planning to update the Science Pipelines tag, you should also check the `Science Pipelines changelog <https://lsst-dm.github.io/lsst_git_changelog/weekly/>`_.
In practice, almost any Science Pipelines update is at least a minor version, because new features are added constantly.
In the future, there may be "patched weekly" builds, which would justify a patch version of Prompt Processing.
**The following changes will trigger a major release:**

For the ``prompt_processing`` service, a new major version is triggered by any of the following:
For the ``prompt_processing`` service:

* Incompatibility with old fanned-out ``nextVisit`` messages (almost any change to ``Visit`` qualifies)
* Incompatibility with an old `APDB schema`_, `ApdbSql`_, `ApdbCassandra`_, or `ApdbCassandraReplica`_ version (see `DMTN-269`_ for the distinction)
* Incompatibility with an old `Butler dimensions-config`_ version
* A new major version of the `Alerts schema`_ (see `DMTN-093`_ for details)
* Incompatibility with old fanned-out ``nextVisit`` messages (almost any change to ``Visit`` qualifies)
* Incompatibility with an old `APDB schema`_, `ApdbSql`_, `ApdbCassandra`_, or `ApdbCassandraReplica`_ version (see `DMTN-269`_ for the distinction)
* Incompatibility with an old `Butler dimensions-config`_ version
* A new major version of the `Alerts schema`_ (see `DMTN-093`_ for details)

For the `next_visit_fan_out`_ service, a new major version is triggered by any of the following:
For the `next_visit_fan_out`_ service:

* Incompatibility with old Summit ``nextVisit`` messages
* Breaking changes in the fanned-out ``nextVisit`` messages (almost any change to ``NextVisitModel`` qualifies)
* Incompatibility with old Summit ``nextVisit`` messages
* Breaking changes in the fanned-out ``nextVisit`` messages (almost any change to ``NextVisitModel`` qualifies)

2. Create a Release
#. Create a Release

On GitHub.com, navigate to the main page of the repository.
To the right of the list of files, click **Releases**.
At the top of the page, click **Draft a new release**.
Type a tag using semantic versioning described in the previous section.
The Target should be the main branch.
On GitHub.com, navigate to the main page of the repository.
To the right of the list of files, click **Releases**.
At the top of the page, click **Draft a new release**.
Type a tag using semantic versioning described in the previous section.
The Target should be the main branch.
Copy link
Member

Choose a reason for hiding this comment

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

I finally figured out what sometimes causes "Previous tag: auto" to pick the wrong version -- when there aren't any (eligible) PRs since the last tag, it goes back to the version before the most recent PR.

Add a note warning that auto is unreliable if there are no changes in PP itself?


Select **Generate Release Notes**.
This will generate a list of commit summaries and of submitters.
Add text as follows.
.. note::

* Any specific motivation for the release (for example, including a specific feature, preparing for a specific observing run)
* Science Pipelines version and rubin-env version
* Supported `APDB schema`_ and `ApdbSql`_/`ApdbCassandra`_/`ApdbCassandraReplica`_ versions (see `DMTN-269`_ for rationale).
A stack quoting a given minor version is compatible with *older* APDBs of that major version but not necessarily newer ones; for example, a release whose baseline is APDB schema 1.4.0 can access a schema 1.0.0 or 1.4.1 database, but not schema 1.5.
* Supported `Butler dimensions-config`_ versions
* The `Alerts schema`_ version used for output (see `DMTN-093`_ for details)
The `auto` option is unreliable if there are no changes in Prompt Processing itself.
In these cases, if there weren't any eligible Pull Requests since the last tag, it may choose an older version than the latest.
Select **Generate Release Notes**.
This will generate a list of commit summaries and of submitters.
Add text as follows:

* Any specific motivation for the release (for example, including a specific feature, preparing for a specific observing run)
* Science Pipelines version and rubin-env version
* Supported `APDB schema`_ and `ApdbSql`_/ `ApdbCassandra`_/ `ApdbCassandraReplica`_ versions (see `DMTN-269`_ for rationale).
A stack quoting a given minor version is compatible with *older* APDBs of that major version but not necessarily newer ones; for example, a release whose baseline is APDB schema 1.4.0 can access a schema 1.0.0 or 1.4.1 database, but not schema 1.5.
* Supported `Butler dimensions-config`_ versions
* The `Alerts schema`_ version used for output (see `DMTN-093`_ for details)

Select **Publish Release**.

The `Release CI <https://github.com/lsst-dm/prompt_processing/actions/workflows/ci-release.yaml>`_ GitHub Actions workflow uploads the new release to GitHub packages.
This may take a few minutes, and the release is not usable until it succeeds.

.. _DMTN-093: https://dmtn-093.lsst.io/#alertmanagement

Expand All @@ -132,17 +157,12 @@ Add text as follows.

.. _ApdbSql: https://github.com/lsst/dax_apdb/blob/main/python/lsst/dax/apdb/sql/apdbSql.py#L71-L75

.. _ApdbCassandra: https://github.com/lsst/dax_apdb/blob/main/python/lsst/dax/apdb/cassandra/apdbCassandra.py#L84-L88
.. _ApdbCassandra: https://github.com/lsst/dax_apdb/blob/main/python/lsst/dax/apdb/cassandra/apdbCassandra.py#L87-L91

.. _ApdbCassandraReplica: https://github.com/lsst/dax_apdb/blob/main/python/lsst/dax/apdb/cassandra/apdbCassandraReplica.py#L52-L56

Copy link
Member

Choose a reason for hiding this comment

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

The ApdbCassandra link has bitrotted again. 😂 Should now be #L87-L91.

.. _Alerts schema: https://github.com/lsst/alert_packet/blob/main/python/lsst/alert/packet/schema/latest.txt

Select **Publish Release**.

The `Release CI <https://github.com/lsst-dm/prompt_processing/actions/workflows/ci-release.yaml>`_ GitHub Actions workflow uploads the new release to GitHub packages.
This may take a few minutes, and the release is not usable until it succeeds.


Patch Releases and Release Branches
-----------------------------------
Expand Down