(chore) O3-1109: Add a GitHub Action to check that PR titles include a version bump marker

[Twiineenock]

Requirements

• This PR has a title that briefly describes the work done including the ticket number. Ensure your PR title includes a conventional commit label (such as feat, fix, or chore, among others). See existing PR titles for inspiration.

For changes to apps

• My work conforms to the O3 Styleguide and design documentation.

If applicable

• My work includes tests or is validated by existing tests.
• I have updated the esm-framework mock to reflect any API changes I have made.

Summary

Per [RFC-31](openmrs/openmrs-rfc-frontend#31), pull request titles must begin with a prefix that signals the type of version bump the change implies, such as:

• (feat) for new features
• (fix) for bug fixes
• (docs) for documentation-only changes
• (test) for test-only updates
• (chore) for tooling or maintenance
• (refactor) for non-functional internal improvements
• BREAKING: for backwards-incompatible changes

Optionally, a ticket number may be included, but it must be correctly formatted to start with an uppercase O3, followed by a dash and digits (e.g. O3-1234). Both lowercase "o" (o3) and numeric zero (03) as the prefix are considered invalid.

---

✅ Valid PR Title Examples

(chore) Remove orders widget feature flag
(chore) Bump @openmrs/ngx-formentry
(fix) O3-2657: Show inline errors when saving orders fails
(feat) O3-2724: Move overlays into the framework
(feat) O3-3063: Appointments dashboard UI tweaks
(test) O3-3040: Add E2E test for adding a visit note
(docs) Add steps for running E2E tests to README
(refactor) Tidy the workspaces implementation
BREAKING: Upgrade to Carbon v11

---

❌ Invalid PR Title Examples

These examples are invalid and will be rejected:

(feat) o3-2657: Use lowercase 'o' in ticket prefix
(fix) 03-2657: Use numeric zero instead of uppercase 'O'
feat: No parentheses around type
fix(O3-2657): Missing space and colon after type
(feat) O3:2657: Wrong separator (should use a dash)
(feat) Some new feature – Missing ticket and colon
update: Add new stuff – "update" is not a valid type
docs Added README – Missing parentheses and colon
(chore): Extra colon after type

---

Why we are using amannn/action-semantic-pull-request instead of actions/github-script

While amannn/action-semantic-pull-request is great for enforcing the [Conventional Commits](https://www.conventionalcommits.org/) standard, it has limitations when it comes to fine-grained customization, especially:

It could not validate (feat) or other valid formats without a subject or ticket in the exact way we wanted.

Despite customizing the headerPattern, we hit a hard wall where titles like (feat) or (docs)—which are valid under our RFC—would be incorrectly rejected, and nuanced errors (like using 03-1234) couldn't be detected flexibly.

For maximum control and clarity, we moved to [actions/github-script](https://github.com/actions/github-script) which gives us full programmatic power to:

• Precisely define what’s valid
• Provide custom error messages
• Allow optional ticket enforcement (when present, it must follow O3-123 format)
• Easily evolve our rules in plain JavaScript

This shift allows OpenMRS to align tightly with our internal contribution standards while still respecting semantic principles.

Screenshots

The following screansshots are example checks

Valid PR Title

No version bump label fails

A zero instead of "O" fails

Related Issue

https://openmrs.atlassian.net/browse/O3-1109

Other

Screancasts

Check passed
passed.webm

Check failed
zero.webm

[Twiineenock]

Hello @brandones !
Just a quick nudge for a review whenever you get a chance—thanks in advance!

[brandones]

Great, thanks @Twiineenock ! I'm going to change the title of this PR a few times just to test it out. I'll change it back when I'm done.

[brandones]

@denniskigen @ibacher I'm of the opinion that refactor should be removed as an option and people should just use fix for refactors. This is because I have seldom seen someone in O3-world use the word "refactor" correctly; most things people call a "refactor" around here are actually features or fixes. What do you think? Are we willing/able/interested to police the use of the (refactor) prefix?

[brandones]

"BREAKING: O3-1109: Add a GitHub Action to check that PR titles include a version bump marker"

fails with

Error: For BREAKING changes with tickets:
• Must use parentheses: "(BREAKING) O3-1234: Description"
• Your title: "BREAKING: O3-1109: Add a GitHub Action to check that PR titles include a version bump marker"

It should pass.

[ibacher]

What do you think?

I'm on-board. I kind of dislike "refactor" anyway, since "refactoring" can describe both changing things in a way that doesn't affect the API and changing it in a way that does.

[brandones]

Please remove support for the refactor label.

Please ensure that "BREAKING: O3-1109: Add a GitHub Action to check that PR titles include a version bump marker" passes.

[ibacher]

I don't think you need all of these. opened and edited should suffice.

[ibacher]

I don't know that we necessarily want to restrict this to only tickets that start with O3-.

[ibacher]

This isn't a format that should be allowed. BREAKING should never have parentheses (we want it to stand out).

[ibacher]

You don't need two patterns for this:

/^\((?:docs|test|chore|fix|feat)\) (?:[A-Z][A-Z0-9]+-\d+: )?\S.*$/

Should match any valid PR. See this diagram.

[ibacher]

Note, too, that we don't actually want to use \s here since the only character allows should be a space. \S (the inverse of \s) is useful, though, as we want the first character of the message to be non-whitespace.

[ibacher]

For BREAKING: the ticket always comes after the :, so BREAKING: O3-1234: Some change. Drawing on the stuff from my previous comment:

/^BREAKING: (?:[A-Z][A-Z0-9]+-\d+: )?\S.+/

[ibacher]

If you really wanted to be nuts:

/^(?:\((?:docs|test|chore|fix|feat)\)|BREAKING:) (?:[A-Z][A-Z0-9]+-\d+: )?\S.+$/

Not sure if that's a good idea or not.

[ibacher]

No need to repeat the whole thing. We're just checking that the start of the line is a parenthesis:

Suggested change

	} else if (/^[^(](docs|test|chore|fix|feat|refactor)/i.test(title)) {
	} else if (/^[^(]/(/i.test(title)) {

[ibacher]

But, of course, we actually want to check that there is at least one pair of parentheses.

[ibacher]

The error messages here look like they're meant to be somewhat additive, but since it's implemented as a series if if ... else statements, you'll only ever get messages from one block.

[ibacher]

Shouldn't this come before we include the issues?

[ibacher]

We should have a check, independent of the check for parentheses that the value in the parentheses is one of our allowable types.

[ibacher]

It's definitely good to check for 03 and o3.

[Twiineenock]

Hi @ibacher @brandones ,
I've refined the regex patterns to follow a more realistic and consistent flow—from label to ticket to description.
Additionally, I've enhanced both the error and success messages to make them clearer and more meaningful for users.