Skip to content

Commit eaf13ed

Browse files
claudeclaude
committed
Add comprehensive issue drafts for Part 02 - Community Health Files & Governance
Created 13 detailed issue drafts covering: - Documentation improvements (G01, G02, G04, G05, G06, G07, G10, G11, G13) - Automation enhancements (G03, G09) - Accessibility standards (G08) - DevEx improvements (G12) Each draft includes: - Complete frontmatter with appropriate labels and references - Comprehensive acceptance criteria and context - DoR/DoD checklists - Step-by-step implementation directions - Testing approaches and success metrics - Estimated effort and dependencies Files: - G01: Schema relocation to schemas/frontmatter/ - G02: Fix stale automation links - G03: Create/remove issue-types.yml - G04: Refresh folder READMEs and cross-links - G05: Fix CHANGELOG/VERSION + versioning policy - G06: Unify AI instructions/prompts hierarchy - G07: Branding agent synopsis - G08: Mermaid accessibility palette + captions - G09: Reconcile labeling docs vs YAML configs - G10: Governance matrix + tighten CODEOWNERS - G11: Live Links index - G12: Stub strategy + optional sync PRs - G13: SECURITY vs SUPPORT routing clarity - README: Summary, priority guide, and creation scripts Total estimated effort: 23-36 hours across 13 issues All drafts follow LightSpeed standards and UK English conventions
1 parent 6e7d5d6 commit eaf13ed

14 files changed

+2744
-0
lines changed

‎drafts/G01-schema-relocation.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
name: "📚 Documentation"
3+
about: "Request new documentation or propose updates/clarifications to existing docs."
4+
title: "[Docs/DevEx] Relocate front-matter schema to `schemas/frontmatter/` and update references"
5+
labels: [type:documentation, status:needs-triage, priority:normal, area:documentation, area:devex, version:v0.2.0]
6+
assignees: []
7+
projects: []
8+
milestone: 'v0.2.0'
9+
type: documentation
10+
references:
11+
- ../CONTRIBUTING.md
12+
- .github/BRANCHING_STRATEGY.md
13+
- .github/AUTOMATION_GOVERNANCE.md
14+
- ../schemas/frontmatter/frontmatter.schema.json
15+
- ../DOCS.md
16+
---
17+
18+
## What documentation is needed?
19+
20+
We need to reorganise the front-matter JSON schema into a dedicated subdirectory and update all references across the repository. The schema currently lives at `schemas/` root but should be moved to `schemas/frontmatter/frontmatter.schema.json` to support future schema additions without confusion.
21+
22+
Additionally, we need to implement CI validation that enforces required front-matter fields (version, category, references) to maintain documentation quality and consistency.
23+
24+
**Current state:**
25+
- Schema exists at root of `schemas/` directory
26+
- No CI validation for required front-matter fields
27+
- Future schemas will cause confusion with flat structure
28+
29+
**Desired state:**
30+
- Schema at `schemas/frontmatter/frontmatter.schema.json`
31+
- All imports and documentation references updated
32+
- CI job validates required fields and fails builds when missing
33+
34+
## Why is this documentation important?
35+
36+
**For contributors:**
37+
- Clear, discoverable schema location reduces onboarding friction
38+
- Automated validation prevents incomplete documentation from being merged
39+
- Organised structure prepares for additional schemas (workflow configs, agent specs, etc.)
40+
41+
**For maintainers:**
42+
- Consistent front-matter across all docs enables automation and indexing
43+
- CI enforcement reduces manual review burden
44+
- Proper organisation supports scalability as documentation grows
45+
46+
**Impact:**
47+
- **High** - Broken imports if references aren't updated systematically
48+
- **Medium** - Confusion when multiple schemas appear later without clear organisation
49+
- Blocks v0.2.0 release if not addressed
50+
51+
## Acceptance Criteria
52+
53+
- [ ] File exists at `schemas/frontmatter/frontmatter.schema.json`
54+
- [ ] All documentation files refer to the new schema path
55+
- [ ] All validator scripts/tools updated with new path
56+
- [ ] CI job added to validate required front-matter fields (version, category, references)
57+
- [ ] CI fails with clear error message when required fields are missing
58+
- [ ] Migration documented in CHANGELOG.md
59+
- [ ] DOCS.md updated to reference new schema location
60+
- [ ] Follows [WordPress documentation standards](https://developer.wordpress.org/coding-standards/inline-documentation/)
61+
- [ ] Documentation is accessible and easy to find
62+
- [ ] Changelog entry prepared for PR
63+
64+
## Additional Context
65+
66+
**Files likely requiring updates:**
67+
- `schemas/` → move schema file to new location
68+
- `DOCS.md` → update schema reference path
69+
- `.github/workflows/` → add or update CI validation job
70+
- Any linting or validation scripts
71+
- Documentation guides that reference schema location
72+
73+
**Migration approach:**
74+
1. Create `schemas/frontmatter/` directory
75+
2. Move schema file to new location
76+
3. Update all import paths (use `git grep` to find references)
77+
4. Add CI validation workflow
78+
5. Test validation with intentionally incomplete front-matter
79+
6. Update docs and changelog
80+
81+
**Telemetry (post-merge):**
82+
- CI run logs show schema validation executing successfully
83+
- PR diff shows all updated paths
84+
- No broken links or import errors in subsequent builds
85+
86+
## References
87+
88+
- [schemas/](https://github.com/lightspeedwp/.github/blob/develop/schemas)
89+
- [DOCS.md](https://github.com/lightspeedwp/.github/blob/develop/DOCS.md)
90+
- [Contribution Guidelines](../CONTRIBUTING.md)
91+
- [Branching Strategy](.github/BRANCHING_STRATEGY.md)
92+
- [Automation Governance](.github/AUTOMATION_GOVERNANCE.md)
93+
94+
---
95+
96+
### Definition of Ready (DoR)
97+
98+
- [ ] Documentation need is clear and well-defined
99+
- [ ] Related docs/issues or files linked
100+
- [ ] Acceptance criteria listed
101+
- [ ] Estimate added: **Medium** (2-3 hours: file move, update refs, CI job)
102+
- [ ] Milestone assigned: v0.2.0
103+
104+
### Definition of Done (DoD)
105+
106+
- [ ] Schema relocated to `schemas/frontmatter/frontmatter.schema.json`
107+
- [ ] All references updated (zero broken imports)
108+
- [ ] CI validation job added and tested
109+
- [ ] Documentation meets org standards and guidelines
110+
- [ ] Changelog entry prepared for PR (CHANGELOG.md)
111+
- [ ] Documentation reviewed for clarity and accessibility
112+
- [ ] PR uses correct branch prefix (`docs/schema-relocation`)
113+
114+
---
115+
116+
## Directions & Next Steps
117+
118+
1. Create feature branch: `docs/schema-relocation`
119+
2. Find all schema references: `git grep -l "schemas/" | grep -E '\.(md|json|ya?ml|js|ts)$'`
120+
3. Create `schemas/frontmatter/` directory structure
121+
4. Move schema file and update all references
122+
5. Add CI validation workflow (GitHub Actions) with required field checks
123+
6. Test validation by creating test doc with missing required fields
124+
7. Update DOCS.md with new schema location
125+
8. Add migration note to CHANGELOG.md
126+
9. Submit PR with reference: `fixes #<issue_number>`
127+
10. Tag @docs-team or maintainer for review
128+
129+
**Branch prefix:** `docs/`
130+
131+
**Related areas:**
132+
- area:docs
133+
- area:devex
134+
- area:automation (for CI validation)
135+
136+
See [Contribution Guidelines](../CONTRIBUTING.md) and [Coding Standards](../instructions/coding-standards.instructions.md).

‎drafts/G02-fix-stale-links.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
name: "📚 Documentation"
3+
about: "Request new documentation or propose updates/clarifications to existing docs."
4+
title: "[Docs/Workflows] Fix stale links after automation move to `/.github/automation`"
5+
labels: [type:documentation, status:needs-triage, priority:normal, area:documentation, area:workflows, version:v0.2.0, link-hygiene]
6+
assignees: []
7+
projects: []
8+
milestone: 'v0.2.0'
9+
type: documentation
10+
references:
11+
- ../CONTRIBUTING.md
12+
- .github/BRANCHING_STRATEGY.md
13+
- .github/AUTOMATION_GOVERNANCE.md
14+
- .github/automation/
15+
- ../README.md
16+
---
17+
18+
## What documentation is needed?
19+
20+
Several documentation files across the repository still reference pre-move automation file paths, resulting in 404 errors and broken links. We need to comprehensively scan the repository and update all references to point to the new `/.github/automation` directory structure on the `develop` branch.
21+
22+
**Current state:**
23+
- Automation files moved to `/.github/automation`
24+
- Multiple docs still reference old paths
25+
- Links result in 404 errors for readers
26+
- Onboarding and operational docs are affected
27+
28+
**Desired state:**
29+
- All documentation references updated to `/.github/automation` paths
30+
- All links point to exact `develop` branch URLs
31+
- Zero 404 errors from documentation links
32+
- Clear navigation for contributors and maintainers
33+
34+
## Why is this documentation important?
35+
36+
**For contributors:**
37+
- Broken links disrupt onboarding and understanding of workflows
38+
- Readers cannot access referenced automation configs and examples
39+
- Frustration and reduced trust in documentation quality
40+
41+
**For maintainers:**
42+
- Risk of updating wrong files when following outdated references
43+
- Increased support burden from confused contributors
44+
- Blocks effective operations and workflow management
45+
46+
**Impact:**
47+
- **High** - Blocks onboarding and operations
48+
- **High** - Damages documentation credibility and trust
49+
- **Medium** - Wastes contributor and maintainer time
50+
51+
## Acceptance Criteria
52+
53+
- [ ] Repository-wide scan produces comprehensive list of old → new path mappings
54+
- [ ] All affected documentation files updated with correct paths
55+
- [ ] All links point to exact `develop` branch URLs (not relative paths that might break)
56+
- [ ] Spot-check of updated links confirms zero 404 errors
57+
- [ ] Link checker tool run shows 100% success rate
58+
- [ ] CHANGELOG.md updated with link hygiene improvements
59+
- [ ] Follows [WordPress documentation standards](https://developer.wordpress.org/coding-standards/inline-documentation/)
60+
- [ ] PR uses correct branch prefix (`docs/fix-automation-links`)
61+
62+
## Additional Context
63+
64+
**Scan strategy:**
65+
```bash
66+
# Find potential old automation references
67+
git grep -n "\.github/workflows" | grep -v "\.github/automation"
68+
git grep -n "workflows/" | grep -E '\.(md|txt)$'
69+
git grep -n "automation" | grep -E '\.(md|txt)$' | grep -v "/.github/automation"
70+
```
71+
72+
**Common old → new path mappings:**
73+
- `.github/workflows/labeler.yml` → `.github/automation/labeler.yml`
74+
- `.github/workflows/labels.yml` → `.github/automation/labels.yml`
75+
- `workflows/` → `.github/automation/`
76+
77+
**Files likely affected:**
78+
- README.md
79+
- DOCS.md
80+
- DEVELOPMENT.md
81+
- AUTOMATION_GOVERNANCE.md
82+
- All files in `docs/` directory
83+
- Workflow and automation documentation
84+
85+
**Testing approach:**
86+
1. Use automated link checker (e.g., `markdown-link-check`, `lychee`)
87+
2. Manual spot-check of high-traffic docs
88+
3. Verify all GitHub URLs resolve correctly
89+
90+
**Telemetry (post-merge):**
91+
- Run link checker tool
92+
- Count 404 errors → target: 0
93+
- Monitor for support requests about broken links → target: ↓
94+
95+
## References
96+
97+
- [.github/automation/](https://github.com/lightspeedwp/.github/tree/develop/.github/automation)
98+
- [README.md](https://github.com/lightspeedwp/.github/blob/develop/README.md)
99+
- [DOCS.md](https://github.com/lightspeedwp/.github/blob/develop/DOCS.md)
100+
- [Contribution Guidelines](../CONTRIBUTING.md)
101+
- [Branching Strategy](.github/BRANCHING_STRATEGY.md)
102+
- [Automation Governance](.github/AUTOMATION_GOVERNANCE.md)
103+
104+
---
105+
106+
### Definition of Ready (DoR)
107+
108+
- [ ] Documentation need is clear and well-defined
109+
- [ ] Related docs/issues or files linked
110+
- [ ] Acceptance criteria listed
111+
- [ ] Estimate added: **Small-Medium** (1-2 hours: scan, update, verify)
112+
- [ ] Milestone assigned: v0.2.0
113+
114+
### Definition of Done (DoD)
115+
116+
- [ ] All old automation paths identified
117+
- [ ] All references updated to `/.github/automation`
118+
- [ ] Link checker shows 0 broken links
119+
- [ ] Documentation meets org standards and guidelines
120+
- [ ] Changelog entry prepared for PR (CHANGELOG.md)
121+
- [ ] Documentation reviewed for clarity and accessibility
122+
- [ ] PR uses correct branch prefix (`docs/fix-automation-links`)
123+
124+
---
125+
126+
## Directions & Next Steps
127+
128+
1. Create feature branch: `docs/fix-automation-links`
129+
2. Run comprehensive scan for old automation references
130+
3. Create old → new path mapping document
131+
4. Update all affected files systematically
132+
5. Run automated link checker tool
133+
6. Manual spot-check of critical documentation
134+
7. Update CHANGELOG.md
135+
8. Submit PR with reference: `fixes #<issue_number>`
136+
9. Tag @docs-team or maintainer for review
137+
138+
**Branch prefix:** `docs/`
139+
140+
**Tools to use:**
141+
- `git grep` for finding references
142+
- `markdown-link-check` or `lychee` for link validation
143+
- Editor find/replace for batch updates
144+
145+
See [Contribution Guidelines](../CONTRIBUTING.md) and [Coding Standards](../instructions/coding-standards.instructions.md).

0 commit comments

Comments
 (0)