Skip to content

Commit e8e5641

Browse files
ashleyshawashleyshaw
authored
Merge pull request #7 from lightspeedwp/develop
Add automation governance and release strategy doc
2 parents 675b97c + 1696ceb commit e8e5641

File tree

1 file changed

+162
-0
lines changed

1 file changed

+162
-0
lines changed

‎AUTOMATION_GOVERNANCE.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Automation Governance & Release Strategy
2+
3+
**LightSpeed Organisation — Community Health Defaults**
4+
_Last updated: 2025-10-10_
5+
6+
---
7+
8+
## Purpose
9+
10+
This document governs **automation for changelog enforcement, release creation, labelling, branching, and project sync** across all LightSpeed repositories. It is intended for inclusion in the `.github` (community health) repository and should be referenced in all repo-level README, CONTRIBUTING, and PR templates.
11+
12+
- **Scope:** All org repos (themes, plugins, blocks, docs, infra)
13+
- **Audience:** Maintainers, contributors, CI/CD engineers, design/dev teams
14+
15+
---
16+
17+
## 1. Principles
18+
19+
- **Automate everything:** Changelogs, releases, labelling, project sync—avoid manual steps and ad-hoc local scripts unless explicitly allowed.
20+
- **Use standard workflows:** Prefer reusable GitHub Actions, scripts, and org-wide config from this repo.
21+
- **Keep a Changelog:** All changes must be traceable, user-facing, and formatted for automated extraction.
22+
- **Semantic versioning:** Release versioning is driven by PR labels and workflow triggers.
23+
24+
---
25+
26+
## 2. Required Workflows & Files
27+
28+
### a. Changelog Enforcement & Compilation
29+
30+
- Every PR must add an entry under **Unreleased** in `CHANGELOG.md` (Keep a Changelog format).
31+
- PR template must include a `## Changelog` section (see [PR Template](https://github.com/lightspeedwp/.github/blob/main/.github/PULL_REQUEST_TEMPLATE.md)).
32+
- CI must fail PRs without valid changelog entries (see enforcement workflow).
33+
34+
### b. Release Automation
35+
36+
- When `develop` merges to `main` (or on release PR to main):
37+
1. Validate tests, build, changelog format.
38+
2. Determine next version (manual input or labels → semver).
39+
3. Move `Unreleased` to `vX.Y.Z (YYYY-MM-DD)` section, open a fresh Unreleased.
40+
4. Tag & create GitHub Release using compiled changelog.
41+
5. Attach built artefacts (ZIP, etc) if required.
42+
6. Optional: update stable tag, README, notify channels.
43+
44+
### c. Labelling & Project Sync
45+
46+
- Use Issue Forms/templates to auto-apply type labels (e.g., `Type: bug`, `Type: enhancement`).
47+
- PRs must be auto-labelled via file globs and/or branch prefix (`feature/*` → `Type: enhancement`).
48+
- Each PR must link its type/area/priority labels to the corresponding Project fields.
49+
- On PR open/label change, add item to relevant Projects board and set status.
50+
- On merge, auto-move item to Done and close linked issues.
51+
52+
### d. Branching Discipline
53+
54+
- Use `{type}/{scope}-{short-title}` branch names (see [Branching Strategy](https://github.com/lightspeedwp/.github/blob/main/.github/branching-strategy.md)).
55+
- Enforce branch name patterns via CI.
56+
- Squash merge only; delete branches post-merge.
57+
58+
---
59+
60+
## 3. Label & Issue Type Policy
61+
62+
- Labels are **routing signals** (status, priority, area/component, environment, compatibility).
63+
- Use exactly one `status:*`, one `priority:*`, and one `area:*` or `comp:*` per item.
64+
- Do _not_ use `type:*` labels—classification lives in the Issue Type field and Project.
65+
- All labels should match org-wide colours and naming (see [Labels Guide](https://github.com/lightspeedwp/.github/blob/main/.github/labels-guide.md)).
66+
- See [Issue Types Guide](https://github.com/lightspeedwp/.github/blob/main/.github/issue-types.md) for classification.
67+
68+
---
69+
70+
## 4. Changelog Format & Release Policy
71+
72+
**Changelog format:**
73+
```markdown
74+
## [Unreleased]
75+
### Added
76+
- User-facing note. (#123, @author)
77+
78+
### Fixed
79+
- Short, clear fix description.
80+
81+
### Changed
82+
- Update details.
83+
84+
### Removed
85+
- Deprecated or removed features.
86+
87+
<!-- If no changelog entry is needed (internal-only), apply the skip-changelog label. -->
88+
```
89+
90+
- Changelog entries should be written for end-users (not just devs).
91+
- The release workflow will extract changelog from PR bodies and labels.
92+
93+
**Release triggers:**
94+
- PR labels (`release:patch`, `release:minor`, `release:major`) determine next version bump.
95+
- If `BREAKING CHANGE:` is found in PR body/commit, force a major bump.
96+
- Release workflow tags and publishes a new GitHub Release with compiled notes.
97+
98+
---
99+
100+
## 5. Recommended Actions & Example Configs
101+
102+
**Actions:**
103+
- Changelog enforcement/compilation: `changelog-enforcer`, `release-please`, `changelog-ci`, `keep-a-changelog-new-release`.
104+
- Release creation: `create-release`, `automatic-releases`, `git-release`, `release-please-action`.
105+
- Label automation: `actions/labeler@v5`, custom scripts.
106+
- Project sync: `actions/add-to-project@v1`, `titoportas/[email protected]`.
107+
108+
**Example configs:**
109+
- See [labels-issues-prs.yml](https://github.com/lightspeedwp/.github/blob/main/.github/workflows/labels-issues-prs.yml)
110+
- See [project-meta-sync.yml](https://github.com/lightspeedwp/.github/blob/main/.github/workflows/project-meta-sync.yml)
111+
- See [labeler.yml](https://github.com/lightspeedwp/.github/blob/main/.github/labeler.yml)
112+
113+
---
114+
115+
## 6. Project Field Alignment
116+
117+
- Ensure single-select fields in Projects match the values mapped from labels and branch prefixes:
118+
- **Status:** Triage, Ready, In progress, In review, In QA, Blocked, Done
119+
- **Priority:** Critical, Important, Normal, Minor
120+
- **Type:** Feature, Bug, Documentation, Task
121+
122+
---
123+
124+
## 7. Secrets & Permissions
125+
126+
- Use repo/org **Environments** for release tokens.
127+
- Limit `GITHUB_TOKEN` permissions; prefer fine-grained PAT only when required.
128+
- Ensure build artefacts are reproducible; no local-only release tooling.
129+
130+
---
131+
132+
## 8. Rollout Plan
133+
134+
1. Add labels, Issue/PR templates, and labeler config to `.github` repo.
135+
2. Enable changelog enforcer, educate devs, iterate categories and enforcement.
136+
3. Ship release workflow behind `workflow_dispatch` for dry-run testing.
137+
4. Switch trigger to `develop → main` (or main-only), monitor and refine.
138+
139+
---
140+
141+
## References
142+
143+
- [GitHub Labels Guide](https://github.com/lightspeedwp/.github/blob/main/.github/labels-guide.md)
144+
- [Issue Types Guide](https://github.com/lightspeedwp/.github/blob/main/.github/issue-types.md)
145+
- [Branching Strategy](https://github.com/lightspeedwp/.github/blob/main/.github/branching-strategy.md)
146+
- [PR Template](https://github.com/lightspeedwp/.github/blob/main/.github/PULL_REQUEST_TEMPLATE.md)
147+
- [Project Templates](https://github.com/lightspeedwp/.github/tree/main/.github/project-templates/)
148+
- [Labelling & Project Automation Workflows](https://github.com/lightspeedwp/.github/tree/main/.github/workflows/)
149+
- [Org instructions for Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-organization-custom-instructions-for-github-copilot)
150+
151+
---
152+
153+
## How to use this document
154+
155+
- Reference this file in repo-level README, CONTRIBUTING, and PR templates.
156+
- Link to it in project onboarding docs and contributor guides.
157+
- Treat as the single source of truth for automation, changelog, release, and labelling policies.
158+
- Update as automation or org-wide standards evolve; changes should be reviewed by maintainers.
159+
160+
---
161+
162+
_This file is maintained by the LightSpeed Tools & Automation team. For updates or questions, open an issue in the `.github` repo or contact #automation-support._

0 commit comments

Comments
 (0)