Add release-please pipeline for release management

[MCatherine1994]

Describe the task
Add release-please pipeline for release management

Acceptance Criteria

• Add the release-please pipeline for managing release tag and generating release note
• Discuss with the team to see how we want to do an initial release

Additional context

• Copy the release-please pipeline from Heartwood https://github.com/bcgov/nr-forests-access-management/blob/main/.github/workflows/release-please.yml

[MCatherine1994]

The github action pipeline repository used by Heartwood is archived in 2024 https://github.com/google-github-actions/release-please-action. So we'll use this repository instead https://github.com/googleapis/release-please-action. All the code are same, they just moved everything to this new repository.

[DerekRoberts]

What are you trying to achieve here? This release action is pure garbage. @SLDonnelly @MCatherine1994

[DerekRoberts]

Here! AI made the argument for me. :)

...

Case Against release-please-action

1. Unclean and Obscured Git History

• Bloated commit logs: The action introduces unnecessary merge commits (chore(main): release ...) into the git history, even for projects that prefer clean, linear history via squash-merging or rebasing. This adds noise that clutters the log and complicates git bisect and other debugging workflows.
• Lost historical context: Version-bumping release commits can appear out of order relative to the features they contain if the release PR isn't merged immediately. This pollutes the git history and makes it difficult to reliably trace which features correspond to a specific release version.
• Irrelevant changelog entries: Commits made within a PR that are later fixed in that same PR can still appear in the changelog, providing noise to release notes. For example, feat: introduce feature A followed by fix: bug introduced in feature A can lead to an irrelevant changelog entry for a bug that was never present on the main branch.

2. Obscured Release Process and Developer Ignorance

• Decouples developers from the release: The PR-based workflow moves the release process "out of band." Developers see their feat commit merged, but are unaware of when their work actually gets released, creating a disconnect between development and delivery. This also breaks a fully automated CI/CD workflow, as it requires a manual approval step.
• Requires manual intervention: It creates a false sense of full automation. A manual step—approving and merging the release PR—is still required. This introduces a potential bottleneck and point of failure, as a forgotten or stuck PR can halt releases.
• Non-intuitive failure recovery: When things go wrong (e.g., a "stuck" PR due to a flaky API call), fixing it requires specific tribal knowledge, such as manually removing an autorelease: pending label, which is not obvious to most developers. This is demonstrated by multiple issues in the release-please repository reporting problems with hung or duplicate PRs.
• Ignores unrecognized commits by default: By default, release-please ignores commits with unrecognized prefixes (including the default commit message for a git revert), which can lead to unexpected versioning and missing entries in the changelog.
• Hides the release process from developers: The release is not tied directly to a developer's merge action. This can make developers oblivious to how releases happen, potentially leading to confusion and a lack of ownership over the release process.

3. Inefficient Use of Resources

• Wasted CI/CD resources: The open release-please PR triggers repeated and often unnecessary CI checks every time a new commit is merged to the main branch. This consumes CI/CD runner minutes and cloud resources for a PR that is just waiting to be merged.
• Extra security configuration: The built-in GITHUB_TOKEN is intentionally limited to prevent infinite workflow loops, meaning subsequent actions (like package publishing) cannot be triggered automatically by the merged release PR. A separate Personal Access Token (PAT) with elevated permissions is required, introducing a security risk and extra maintenance overhead.
• Resource drain on Openshift (or other CI/CD platforms): The lingering release-please PRs chew up resources by consistently triggering checks. For busy repositories, this becomes a persistent drain on the build system.
• No built-in package publishing: release-please focuses on changelog generation and creating GitHub releases. It does not automatically publish to package managers like npm or PyPI, requiring you to set up separate, additional workflows for this purpose.

4. Fragile Automation and Reliability Issues

• Known failure modes: The action has documented failure modes, such as stuck PRs caused by GitHub API failures, requiring manual intervention to get the process running again. Users have reported issues where the action fails to create releases or finds incorrect release PRs.
• Flaky API calls: Users have reported intermittent issues like 502 Bad Gateway errors when the action tries to fetch merge commits, leading to random pipeline failures.
• Complex for monorepos: While it supports monorepos, the configuration and behavior can be fragile and unintuitive. Issues with the manifest file and versioning race conditions are common frustrations, leading to unexpected behavior and manual cleanup.
• Inconsistent version-bumping logic: Some users have reported issues where the action fails to correctly parse valid conventional commit messages, or is broken by unintended characters like emojis, leading to broken changelogs and version bumps.
• Less transparent than storing changelog in repo: By default, changelogs are generated and stored only on GitHub Releases. Unlike keeping a CHANGELOG.md file within the repository, this can be an external system risk, making the release history less accessible, searchable, and migratable.
• "Surprise" version bumps: A bug in version 4 of the action caused the releases_created output to always be true, regardless of whether a release was created, leading to unexpected deployments.

[paulushcgcj]

Any suggestion @DerekRoberts ?

On client, we use TriPSs/conventional-changelog-action to generate the contents of the change, and we pair it with softprops/action-gh-release to generate a release. If I'm not mistaken, part of the validation also uses TriPSs/conventional-changelog-action to validate the PR name.

I'm a fan of using releases to track changes as artifacts. On client, @DerekRoberts adjusted our workflow only to generate releases after it reaches prod, to reduce the noise in between releases. Also, as we have manual control over what goes to prod (with an approval gate) and it helps with grouping changes into releases.

Unfortunately, our workflow is not tailored to versioning, making it not that relevant in terms of usefulness, so for the DevOps team is usually seen as irrelevant, but for bureaucratic reasons, like generating reports to the higher-ups, it helps to generate either a report or at least a baseline on what changes in between releases.

I think we should always strike a balance between what is needed and what is useful, but in the end, I think the team should have the final decision when it comes to things that matter to the team, and supporting roles should help the team achieve what they need through recommendations and support. If something is too off to be handled with a generic approach (AKA Oracle database management in the tools namespace, for example), it should be directed to be handled in a separate, through a different workflow that can be split to not interfere with the main workflow that is generic, or through documentation.

One thing that we have to keep in mind is that no matter how much we want to keep things in line, different projects will inevitably end up with different requirements, which will force changes to the status quo of what we expect in terms of replicability. That's why it is important to foment a healthy discussion on what can be reused, what can be adapted and what is not ideal, leaving some room for customization.

Let me know if you folks want to jump on a chat for a discussion on what the expectation is, so we can come up with a solution that can benefit the team, while still keeping the workflow sustainable.

[webgismd]

Is this something we would benefit hammering out in a mtg to discuss? either QP 2 agenda topic? or dev chat? I would like to help clearly define how Derek can support teams, and keep as much consistency across the teams, while also meeting needs to teams and listening to challenges and discussing solutions. --> so folks understand rationale for devops decisions and practices.