chore(release): promote v1.53.0

[fredcamaral]

GitHub Actions Shared Workflows

---

Description

Promotes the validated develop state to main for the stable v1.53.0 release.

This release makes the Breaking Change Guard mandatory for every caller of the PR validation, Go validation, and JS/TS validation workflows. The guard runs for every pull request target branch, including drafts, and enforces through the existing Blocking Checks status.

There is no enable input, branch filter, configurable acknowledgement, or guard opt-out. A breaking PR requires the exact visible author acknowledgement documented by the workflows. The acknowledgement records author awareness and does not grant maintainer authorization.

Detection, enforcement, public outputs, reporting, Slack, and feedback comments fail closed for unsupported events, shallow history, malformed outputs, cancelled jobs, and blocking-runtime failures.

Caller trigger configuration must include edited so acknowledgement changes rerun validation and ready_for_review so full validation reruns when a draft becomes ready.

Develop published v1.53.0-beta.1 successfully: https://github.com/LerianStudio/github-actions-shared-workflows/actions/runs/31105902523

Type of Change

• feat: New workflow or new input/output/step in an existing workflow
• fix: Bug fix in a workflow (incorrect behavior, broken step, wrong condition)
• perf: Performance improvement (e.g. caching, parallelism, reduced steps)
• refactor: Internal restructuring with no behavior change
• docs: Documentation only (README, docs/, inline comments)
• ci: Changes to self-CI (workflows under .github/workflows/ that run on this repo)
• chore: Dependency bumps, config updates, maintenance
• test: Adding or updating tests
• BREAKING CHANGE: Callers must update their configuration after this PR

Breaking Changes

None. The workflow remains on v1 by product decision. Callers must include edited and ready_for_review in their pull_request activity types for complete revalidation.

Testing

• YAML syntax validated locally
• Triggered a real workflow run on a caller repository using @this-branch or the beta tag
• Verified all existing inputs still work with default values
• Confirmed no secrets or tokens are printed in logs
• Checked that unrelated workflows are not affected

Caller repo / workflow run: Develop beta release v1.53.0-beta.1: https://github.com/LerianStudio/github-actions-shared-workflows/actions/runs/31105902523. Local validation passed 47 workflow-state tests and 56 detector tests.

Related Issues

Related PR: #653.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 420a9b33-d18a-4e5c-9513-78c6d8cfb9de

📥 Commits

Reviewing files that changed from the base of the PR and between 03fe6d9 and 7455991.

📒 Files selected for processing (4)

• .github/workflows/pr-validation.yml
• docs/pr-validation.md
• src/validate/breaking-change-guard/detect.sh
• src/validate/breaking-change-guard/test.sh

---

Summary by CodeRabbit

• New Features

  • Added mandatory breaking-change detection and author acknowledgement to pull request validation.
  • Added flexible acknowledgement matching, including exact visible-line matching.
  • Exposed breaking-change and blocking-check results for workflow reporting.
  • Added feedback for breaking changes and blocking-check runtime failures.

• Bug Fixes

  • Validation now fails safely on unexpected event or check results.
  • Draft pull requests are handled consistently.

• Documentation

  • Updated workflow, trigger, output, enforcement, and acknowledgement guidance.

• Tests

  • Expanded coverage for detection, matching, workflows, and failure handling.

Walkthrough

The PR makes breaking-change detection mandatory in PR validation, adds normalized guard outputs, reports blocking runtime state downstream, adds workflow regression tests, and updates workflow and action documentation.

Changes

Breaking-change guard enforcement

Layer / File(s)	Summary
Guard match mode and detector behavior src/validate/breaking-change-guard/*	The guard supports contains and exact-visible-line acknowledgement matching. The detector validates modes and excludes comments and fenced code in strict mode.
PR validation guard and enforcement wiring .github/workflows/pr-validation.yml	The workflow runs a fail-closed guard, gates blocking checks, applies draft-aware conditions, manages breaking-change comments, and includes guard results in reports and notifications.
Forwarded outputs and runtime-failure reporting .github/workflows/go-pr-validation.yml, .github/workflows/js-pr-validation.yml, src/notify/pr-validation-reporter/*, src/validate/pr-checks-summary/*	Reusable workflows forward guard outputs. Reporter and summary actions process blocking-checks-result and report non-success runtime results.
Workflow regression coverage src/validate/breaking-change-guard/test-workflow.py, .github/workflows/self-pr-validation.yml	The tests cover event validation, fail-closed normalization, enforcement, workflow wiring, action metadata, permissions, and self-validation integration.
Workflow and usage documentation docs/pr-validation.md, docs/go-pr-validation.md, docs/js-pr-validation.md, src/validate/breaking-change-guard/README.md, src/notify/pr-validation-reporter/README.md, src/validate/pr-checks-summary/README.md	The documentation describes matching modes, mandatory enforcement, outputs, draft and dry-run behavior, caller trigger requirements, branch protection, and updated workflow references. Caller documentation removes min_description_length and adds the new outputs.

Estimated code review effort: 4 (Complex) | ~70 minutes

Possibly related PRs

• LerianStudio/github-actions-shared-workflows#653: Modifies the same guard workflows, actions, tests, and documentation.
• LerianStudio/github-actions-shared-workflows#649: Introduces the Breaking Change Guard extended by this PR.
• LerianStudio/github-actions-shared-workflows#651: Modifies the reporter and summary actions extended with runtime-result handling.

Suggested reviewers: bedatty

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary release promotion to stable version v1.53.0.
Description check	✅ Passed	The description includes all required sections and explains the guard behavior, caller requirements, testing, and validation results.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch develop

---

_{Comment @coderabbitai help to get the list of available commands.}

[lerian-studio]

🔍 Lint Analysis

Check	Files Scanned	Status
YAML Lint	7 file(s)	✅ success
Action Lint	4 file(s)	✅ success
Pinned Actions	7 file(s)	✅ success
Markdown Link Check	6 file(s)	✅ success
Spelling Check	16 file(s)	✅ success
Shell Check	7 file(s)	✅ success
README Check	7 file(s)	✅ success
Composite Schema	3 file(s)	✅ success
Deployment Matrix	no changes	⏭️ skipped

---

_{🔍 View full scan logs}

[lerian-studio]

🔍 PR Validation Summary

✅ PR Mergeable — no blocking failures

Check	Status	Blocking
Source Branch	✅ success	yes
PR Title	✅ success	yes
PR Description	✅ success	yes
Breaking Change Guard	✅ success	yes
PR Size	✅ success	no
Auto Labels	✅ success	no
PR Metadata	✅ success	no

---

_{🔍 View workflow run}

[lerian-studio]

🛡️ CodeQL Analysis Results

Languages analyzed: actions

✅ No security issues found.

---

_{🔍 View full scan logs | 🛡️ Security tab}

[coderabbitai]

Warning

CodeRabbit couldn't request changes on this pull request because it doesn't have sufficient GitHub permissions.

Please grant CodeRabbit Pull requests: Read and write permission and re-run the review.

👉 Steps to fix this

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/pr-validation.yml:
- Line 223: Update the pr-description action reference in the workflow to use
the immutable release tag `@v1` instead of the mutable `@develop` branch, matching
the other internal shared-workflow references before promoting to main.

In `@docs/pr-validation.md`:
- Line 76: Update the four production workflow examples using
LerianStudio/github-actions-shared-workflows so their references point to the
immutable `@v1.53.0` tag instead of `@v1`. Leave examples using `@develop` or
`@feat/`<branch> unchanged for testing.

In `@src/validate/breaking-change-guard/detect.sh`:
- Around line 184-186: Update the acknowledgement matching logic around the line
comparison in the validation script to reject acknowledgement values with
leading or trailing whitespace and any blockquote-form acknowledgement beginning
with “>” before evaluating equality. Preserve exact-visible-line matching for
valid ACK values, and add regression cases covering ACK values with edge
whitespace and blockquote syntax.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4e4fc8e4-19d4-445b-a34f-165eaa67c3cd

📥 Commits

Reviewing files that changed from the base of the PR and between 1d294a0 and 03fe6d9.

📒 Files selected for processing (16)

• .github/workflows/go-pr-validation.yml
• .github/workflows/js-pr-validation.yml
• .github/workflows/pr-validation.yml
• .github/workflows/self-pr-validation.yml
• docs/go-pr-validation.md
• docs/js-pr-validation.md
• docs/pr-validation.md
• src/notify/pr-validation-reporter/README.md
• src/notify/pr-validation-reporter/action.yml
• src/validate/breaking-change-guard/README.md
• src/validate/breaking-change-guard/action.yml
• src/validate/breaking-change-guard/detect.sh
• src/validate/breaking-change-guard/test-workflow.py
• src/validate/breaking-change-guard/test.sh
• src/validate/pr-checks-summary/README.md
• src/validate/pr-checks-summary/action.yml

[fredcamaral]

@BlackSmith -- pontos aqui...

[blacksmith-sh]

Got it, I'm reviewing the PR comment now.

[blacksmith-sh]

@fredcamaral

@BlackSmith -- pontos aqui...

Revisei o diff main...develop (16 arquivos, guard obrigatório + enforcement + reporting). Pontos, do mais crítico ao menor:

1. pr-description@develop vai entrar na tag estável. .github/workflows/pr-validation.yml:223 ainda aponta para um branch mutável. Ao promover, pr-validation.yml@v1 passa a executar, em todos os callers, o que estiver em develop naquele instante. Isso contraria a regra de pinning do AGENTS.md e não é reprodutível. É pré-existente no main, mas uma promoção é exatamente o momento de corrigir.

2. acknowledgement-match-mode degrada silenciosamente (único ponto fail-open). A linha 140 usa breaking-change-guard@v1, e hoje v1 = v1.52.0, que não tem esse input (confirmei: ausente em origin/main). Enquanto o v1 não for removido para v1.53.0, o GitHub só emite warning de "unexpected input" e o matching cai de volta para contains sem falhar. Todo o resto do design é fail-closed; esse caso não é. Vale expor um output tipo match-mode-used no action e falhar quando vier vazio, para o workflow detectar action antiga.

3. Falsos positivos no detector (detect.sh:86). O regex ^[[:space:]|*]*breaking changes?(:|[[:space:]])+ aceita * e | como prefixo. Testei localmente contra o script real:

**Breaking Changes:** None.        -> has-breaking-changes=true
| Breaking Changes | none |        -> has-breaking-changes=true

Como o corpo do squash-merge carrega a descrição da PR, qualquer caller cujo template use heading em negrito ou tabela com essa palavra passa a ser marcado como breaking. Antes era advisory; agora é obrigatório e fail-closed, então isso bloqueia merge. Sugiro exigir a forma footer do Conventional Commits (BREAKING CHANGE: em caixa alta) ou, no mínimo, ignorar linhas cujo valor após : seja vazio/none.

4. Draft fica com check vermelho e zero explicação. blocking-checks agora roda com if: always() e enforça o guard em draft, mas Breaking Change Comment (linha 335) e PR Validation Report (425) são gateados por draft != true. O autor de um draft vê "Blocking Checks" falhando e só descobre o motivo abrindo o run. Liberar o comentário do guard em draft resolve, já que é o único canal de feedback ali.

5. O check "Breaking Change Guard" mostra verde quando a detecção falha. Todos os steps do job são continue-on-error: true e o normalize roda com always(), então o job praticamente nunca falha; o sinal real está em outputs.result. Na lista de checks do GitHub o revisor vê o guard passando e o Blocking Checks vermelho. Ou o job falha junto, ou renomeia para deixar claro que é só detecção.

6. "Breaking Changes: None." na descrição não bate com o efeito nos callers. Blocking Checks passa a rodar (e falhar) em draft, onde antes era pulado por completo; os triggers precisam ganhar edited e ready_for_review; e há novos outputs no contrato do workflow. Repositório com "Blocking Checks" como required status vai ver draft vermelho no dia seguinte. O pre-merge check do CodeRabbit apontou o mesmo. Pelas regras que esta própria PR institui, isso pediria a linha de acknowledgement.

7. Custo e ruído com edited obrigatório. Cada edição de descrição dispara um run completo com fetch-depth: 0 (linhas 133 e 272), inclusive em draft, e não há concurrency em pr-validation.yml nem nos exemplos de docs/pr-validation.md. Vale documentar concurrency: { group: pr-validation-${{ github.event.pull_request.number }}, cancel-in-progress: true } no snippet do caller.

8. has_breaking_changes: false é ambíguo. Vale tanto para "não há breaking change" quanto para "a detecção falhou". O detection-succeeded existe no job mas não é exposto como output do workflow. A doc manda ler breaking_change_result antes, mas quem gatear um job de release major direto no booleano cai na armadilha; expor detection_succeeded elimina isso.

9. test-workflow.py (692 linhas) valida YAML por regex/substring. A parte que extrai e executa os run: é boa, mas extract_step casa nomes literais de step, então qualquer rename quebra a suíte sem que o comportamento mude. Dívida aceitável, só ficar ciente.

Menor: slack-notify.yml@v1.28.12 (linha 448) continua pinado numa versão antiga enquanto o resto migrou para @v1.

Nada aqui bloqueia a promoção por si só, mas eu trataria o item 1 antes do merge (é um segundo de trabalho e sai na tag estável) e o item 3 antes de o guard virar obrigatório para toda a org.