ADR Suggestion Auto-generated Release Pull Requests (develop → master)

[AndrewSazonov]

Currently, in most EasyScience projects, a pull request from develop to master has to be created manually every time a new release is prepared. This usually means opening GitHub, selecting branches, writing a title and description, etc.

To simplify this process and make it more consistent across all EasyScience repositories, I suggest adding a standard GitHub workflow that automatically creates this release PR.

The workflow can be triggered manually via workflow_dispatch by clicking the “Run workflow” button in the Actions tab. After a single click, the EasyScience bot creates a pull request from develop (or another specified branch) into master, using a predefined title, description and label. This replaces the full manual PR creation process with one simple action.

To allow more flexibility, the workflow includes an input field “Source branch to create PR from”. By default, this is set to develop, but it can be changed to another branch, such as e.g. hotfix, if needed.

The created PR is automatically labeled [bot] pull request, which clearly marks it as automation-generated and excludes it from release notes and version bump logic. The introduction of this label is described in a separate ADR suggestion (#49).

Below is a draft of the proposed workflow included to the EasyScience Copier templates.

https://github.com/easyscience/templates/blob/master/template/.github/workflows/release-pr.yml

# This workflow creates an automated release PR from a source branch into the default branch.
#
# Usage:
#   - Triggered manually via workflow_dispatch.
#   - Creates a PR titled "Release: merge <source> into <default>".
#   - Adds the label "[bot] pull request" so it is excluded from changelogs.
#   - The PR body makes clear that this is automation only (no review needed).

name: 'Release PR (<source> → <default>)'

on:
  workflow_dispatch:
    inputs:
      source_branch:
        description: 'Source branch to create PR from'
        required: false
        default: 'develop'
        type: string

permissions:
  contents: read
  pull-requests: write

env:
  DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
  SOURCE_BRANCH: ${{ inputs.source_branch || 'develop' }}

jobs:
  create-pull-request:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout ${{ env.SOURCE_BRANCH }} branch
        uses: actions/checkout@v5
        with:
          ref: ${{ env.SOURCE_BRANCH }}

      - name: Setup easyscience[bot]
        id: bot
        uses: ./.github/actions/setup-easyscience-bot
        with:
          app-id: ${{ vars.EASYSCIENCE_APP_ID }}
          private-key: ${{ secrets.EASYSCIENCE_APP_KEY }}

      - name: Create PR from ${{ env.SOURCE_BRANCH }} to ${{ env.DEFAULT_BRANCH }}
        env:
          GH_TOKEN: ${{ steps.bot.outputs.token }}
        run: |
          gh pr create \
            --base ${{ env.DEFAULT_BRANCH }} \
            --head ${{ env.SOURCE_BRANCH }} \
            --title "Release: merge ${{ env.SOURCE_BRANCH }} into ${{ env.DEFAULT_BRANCH }}" \
            --label "[bot] pull request" \
            --body "This PR is created automatically to trigger the release pipeline. It merges the accumulated changes from \`${{ env.SOURCE_BRANCH }}\` into \`${{ env.DEFAULT_BRANCH }}\`.

            ⚠️ It is labeled \`[bot] pull request\` and is excluded from release notes and version bump logic."

[rozyczko]

Creating the release merge is a simple task. Automating the process means more code to maintain.

Does automation really improve consistency over a well-documented manual process?

CI checks before PR creation - those should be run before the PR is created.

[AndrewSazonov]

Automating the process means more code to maintain.
Does automation really improve consistency over a well-documented manual process?

The proposed workflow itself is quite small and simple, so I personally don’t see it as a maintenance problem. In practice, we either maintain a small piece of workflow code or we maintain documentation that explains how to do the same thing manually. Both require effort, but automation removes the need for people to remember, search for, and follow the steps every time.

From my own experience, creating release PRs manually is surprisingly annoying. Each time, I ended up looking at old PRs to remember:

• what the title was and how it was formatted,
• what the description looked like,
• which labels were used.

Even with a well-written guide, I would still need to:

• find that guide,
• read it again,
• copy or rewrite the title and description,
• set an appropriate label,
• check that I didn’t miss anything.

With the workflow, all of this becomes one click. The result is always the same. That is where I see the main consistency benefit: not only documented consistency, but enforced consistency.

This also follows a common CI/CD best practice: if something is repetitive, mechanical, and needs to look the same every time, it is usually a good candidate for automation.

CI checks before PR creation - those should be run before the PR is created.

The suggested workflow is purely a PR-creation helper, not a replacement for validation. It does exactly what a human would do manually: create a PR with a standard title, description, and label.

All actual CI checks would still run on the PR as usual, just like today.

[rozyczko]

The proposed workflow itself is quite small and simple, so I personally don’t see it as a maintenance problem.

At THIS moment. Consider potential improvements, versioning, additional tests (e.g. do we do the PR if there's no difference between develop and master and someone just clicked wrong?),
The script doesn't update the release notes nor does anything else of value.
We still have to create the release with notes, tagging etc.

This script only clicks on "Create PR" button, really - how is it less demanding than doing it manually?

In practice, we either maintain a small piece of workflow code or we maintain documentation that explains how to do the same thing manually

Making a develop -> master PR means we are preparing for the release. This process is much more involving than just clicking the PR button. Maybe we should automate the release preparation process as a whole, instead?

[rozyczko]

The proposed workflow itself is quite small and simple, so I personally don’t see it as a maintenance problem.

At THIS moment. Consider potential improvements, versioning, additional tests (e.g. do we do the PR if there's no difference between develop and master and someone just clicked wrong?),
The script doesn't update the release notes nor does anything else of value.
We still have to create the release with notes, tagging etc.

This script only clicks on "Create PR" button, really - how is it less demanding than doing it manually?

In practice, we either maintain a small piece of workflow code or we maintain documentation that explains how to do the same thing manually

Making a develop -> master PR means we are preparing for the release. This process is much more involving than just clicking the PR button. Maybe we should automate the release preparation process as a whole, instead?

[AndrewSazonov]

At THIS moment. Consider potential improvements, versioning, additional tests (e.g. do we do the PR if there's no difference between develop and master and someone just clicked wrong?),

I’m not sure we really need extra logic, versioning, or tests for this workflow. If someone clicks the wrong button in the Actions tab, the same person could just as easily click the wrong “Create PR” button in the GitHub UI today. There is no strong protection against this in the manual process either.

The proposed workflow is meant as a convenience helper. It will work correctly most of the time and save time. If something goes wrong, the result is simply a PR that can be closed, or the PR can be created manually instead. Nothing irreversible happens.

The script doesn't update the release notes nor does anything else of value.
We still have to create the release with notes, tagging etc.

That is expected. This workflow is not intended to handle release notes, version tagging, or publishing. Those steps are already covered by other workflows that runs after merging into master.

This workflow only replaces the manual PR creation step. Everything that happens after merge stays exactly the same as today and still requires human approval.

This script only clicks on "Create PR" button, really - how is it less demanding than doing it manually?

It does more than just clicking a button. It also:

• sets a predefined, consistent title,
• adds a standard description,
• applies the correct label automatically.

For me, this is the main value. Instead of:

• clicking several buttons,
• selecting branches,
• writing or copy-pasting the title,
• writing or copy-pasting the description,
• remembering which label to use,

you click one button and everything is filled in the same way every time.

This is not about adding new functionality, but about reducing repetitive manual work and removing small but constant sources of inconsistency.

Making a develop -> master PR means we are preparing for the release. This process is much more involving than just clicking the PR button. Maybe we should automate the release preparation process as a whole, instead?

Release preparation is a multi-step automated process that intentionally includes intermediate points for human approval.

The process looks like this:

1. Create PR (develop → master)
   Today this is fully manual: open PR page, select branches, write title, write description, add label.
   My suggestion replaces this with one explicit human action: clicking “Run workflow”.
2. CI runs on the PR
   Tests, label checks, docs build, etc.
3. Human review and merge
   When CI is green, someone explicitly clicks “Merge”.
4. Release preparation and publishing
   Merging into master triggers workflows that prepare release notes and suggest a new version/tag.
   A human still reviews and clicks “Publish release”.
5. Post-release automation
   Docs deploy, PyPI publish, backmerge, etc.

So the whole flow is already automated between intentional human approval points.
The proposed workflow only simplifies step 1, without changing any responsibilities or control points.

[rozyczko]

I still don't see a reason to make it a separate action unconnected to 2.
We still want to run CI, tests etc before tagging/release prep.

Can you not merge 1. and 2. into a workflow which creates the PR and runs tests, checks, docs?
Also, don't docs get build on tag rather than on master merge?

This would be then

1. Initial preparation (your steps 1. and 2.)
2. Manual approval on success MERGE
3. MERGE triggers release publish with tag assignment and docs build
4. Manual approval on success PUBLISH
5. PUBLISH triggers deployment of docs to ghpages, package to pypi, backmerge

[AndrewSazonov]

Can you not merge 1. and 2. into a workflow which creates the PR and runs tests, checks, docs.

I don’t think these two steps can be fully merged.

Step 1 is an explicit human decision: someone decides that the project is ready for a release and starts the process by creating a PR from develop to master. This can be done fully manually, or semi-automatically with the suggested workflow, but it still needs a human action.

Step 2 only makes sense after the PR exists. All CI checks (tests, docs, labels, etc.) are naturally triggered by the PR itself. So step 2 is already connected to step 1 through the normal GitHub PR process.

I also want to clarify that this ADR only focuses on automating step 1: creating the release PR in a consistent and simple way.

To avoid confusion, I created another ADR suggestion (#88) with a more detailed description of the whole release workflow, including CI, tagging, publishing, docs, and backmerge. This ADR should be seen as a small part of that bigger flow.

Please have a look at ADR #54 - I think it explains the full picture better.