XeplosionTechnologies/.forgejo

Watch

Fork

You've already forked .forgejo

Code Issues 19 Pull requests Projects 5 Releases Packages Wiki Activity Actions

Complete `.forgejo` canonical automation and template modernization #41

New issue

Open

opened 2026-09-07 22:33:47 +00:00 by Xeplosion · 0 comments

Xeplosion commented

2026-09-07 22:33:47 +00:00

Owner

Copy link

Type of chore

Repository / project maintenance

What needs to be done and why?

Complete the modernization of .forgejo as the canonical repository for shared repository templates, synchronization, CI/CD workflows, issue/PR templates, and related automation.

The previous overhaul issue accumulated completed work, superseded architectural assumptions, documentation tasks, security work, feature requests, and bug fixes into one large checklist. The repository architecture and project structure have since become clearer.

This replacement should remain a governing issue for the health of the canonical .forgejo automation system while substantial independent work is split into focused child issues.

Canonical architecture

Confirm main is the canonical source for shared executable/template assets.
Confirm template branches contain stack-specific template state.
Confirm managed template repositories are downstream artifacts rather than competing sources of truth.
Confirm docs contains concise standards/reference documentation.
Confirm the Wiki contains contributor-facing operational guidance.
Remove stale comments or documentation that contradict this model.

Shared synchronization

Audit sync-config.yml.
Confirm all intended shared files are represented.
Confirm stack-specific assets are not incorrectly treated as shared.
Confirm directory synchronization works for ISSUE_TEMPLATE/.
Confirm shared-file overwrite behavior.
Confirm additive/removal behavior is intentional.
Document the process for intentionally removing previously synced files.
Test synchronization against a controlled template branch.
Test synchronization across all template branches.
Confirm synchronization failures are clear and actionable.

Template-branch validation

Inventory every active template branch.
Define required branch-specific files for each.
Confirm validation runs before template publication.
Confirm missing required assets fail validation.
Confirm invalid shared/template state cannot silently publish.
Review whether additional structural validation is needed.

Template publication

Confirm every template branch maps to the intended template repository.
Confirm normal publication behavior.
Confirm fallback PR behavior when direct publication is blocked.
Confirm publication does not destroy intentional branch-specific state.
Confirm template repositories are clearly identified as managed.
Test publication against a disposable or controlled template target.

Workflow inventory / cleanup

Inventory every canonical workflow.
Remove obsolete workflows.
Confirm workflow names describe their actual behavior.
Confirm triggers match intended behavior.
Confirm runner labels match current infrastructure.
Confirm required tooling is installed rather than assumed.
Standardize variables versus secrets.
Standardize handling of workflow tokens.
Add comments for non-obvious behavior.
Remove stale references to retired infrastructure.
Validate high-impact changes through the workflow-validation repository when available.

Deployment / operations workflows

Confirm production deployment matches the current architecture.
Confirm test deployment matches the current architecture.
Confirm pre/post-deployment validation.
Confirm rollback orchestration supports stack-specific implementations.
Link the PHP rollback bug.
Confirm scheduled health-check behavior.
Confirm failure notifications are useful and current.

Releases

Confirm release trigger behavior.
Confirm Conventional Commit grouping.
Confirm breaking-change handling.
Confirm artifact behavior.
Confirm release-token requirements and scope.
Confirm repositories that do not release artifacts are not forced into unnecessary release behavior.

Canonical issue / PR templates

Confirm all canonical issue templates match the current issue lifecycle.
Confirm obsolete Branch/ label references are removed.
Link the WIP pull-request workflow issue.
Link the issue/PR resolution-alignment issue.
Confirm the final PR template can support both WIP and review-ready PRs.
Confirm shared contributor templates propagate correctly.
Confirm templates remain on main, not docs.

Repository assets / configuration

Audit labels.yml.
Decide/document label-provisioning behavior.
Audit the current configuration-file model.
Track the eventual xegames.config → xetech.config migration separately if still desired.
Confirm canonical reference configuration is distinct from stack-specific defaults.
Audit reference scripts/stubs.
Standardize reference-file comments/banners.
Confirm line-ending rules are intentional.
Confirm .editorconfig / .gitattributes behavior.

Security / protections

Confirm branch protection on main.
Confirm protection on template branches.
Confirm CODEOWNERS coverage.
Confirm synchronization credentials are appropriately scoped.
Confirm canonical workflows do not receive unnecessary secrets.
Link host-side and credential-isolation work rather than duplicating it here.

Documentation alignment

Confirm README.md reflects the current .forgejo repository architecture.
Confirm WORKFLOW.md reflects current Git/automation behavior.
Confirm ISSUES.md reflects current lifecycle behavior.
Confirm LABELS.md reflects the current taxonomy.
Confirm PULL_REQUESTS.md reflects current PR behavior.
Confirm Completed terminology is used consistently.
Confirm Reviewed/ terminology is used consistently.
Confirm lifecycle example references use Example #1–#6 wording.
Link the governing Wiki issue.
Split documentation-specific work into the Standards & Documentation project when appropriate.

Issue decomposition

Re-evaluate every unfinished item from the old overhaul issue.
Mark superseded assumptions as intentionally superseded.
Create focused child issues for independent work.
Put child issues in the project that actually owns the work.
Link child issues to this governing issue.
Avoid allowing this issue to become another unbounded implementation checklist.

Completion criteria

Canonical workflows have been audited.
Template branches have been validated.
Synchronization and publication have been tested.
Known independent problems have dedicated issues.
Current documentation matches actual behavior.
Current security follow-ups are linked.
No retired architecture is presented as current.
A final modernization summary is recorded.

Technical-debt impact

Technical debt in .forgejo propagates.

Incorrect or duplicated assumptions in the canonical automation system become defaults in future managed repositories, multiplying maintenance cost rather than remaining local.

Risk / compatibility impact

High-impact workflow and template changes can affect many repositories.

Develop them on implementation branches, validate against controlled targets, and use explicit review before broad propagation.

Changes to the propagation model should be treated carefully when existing managed repositories rely on current behavior.

Affected branch(es)

main — canonical automation and shared templates
template branches — stack-specific template behavior where required
docs — separate documentation work only

Additional context

The old umbrella issue had already completed many workflow rewrites but still mixed sync correctness, docs, security, features, and obsolete conventions together.

This replacement intentionally uses child issues for independent work while retaining an overall modernization checkpoint.

Request checklist

I described why this work provides value or avoids future technical debt
I identified known risk, compatibility, or coordination concerns where applicable

Workflow lifecycle

Triage

Kind/ classification confirmed
Issue validity reviewed and appropriate Reviewed/ label assigned
Priority/ assigned when appropriate
Implementation branch referenced on the issue through Forgejo when applicable
Information requirements resolved; no Status/Needs More Info remains
Status/Needs Triage removed before leaving Triage

Backlog

Issue is confirmed valid and accepted into the project backlog

To Do

Scope and expected outcome are sufficiently defined
Known prerequisites, dependencies, and required decisions are resolved or understood
Work has been deliberately selected as upcoming work

In Progress

Assignee or active owner identified when appropriate
Forgejo timer started when time tracking provides meaningful value
Relevant implementation, research, or work notes recorded as needed
Forgejo timer stopped when active work ends, pauses, or becomes blocked

Review Gate

Review requirement assessed based on complexity, criticality, reversibility, and impact
If review is required: moved to In Review and appropriate testing / validation performed
If review is required: review comment records what was reviewed, how it was validated, findings, and outcome
If review is not required: rationale is evident from the low-risk nature of the change

Completed

Acceptance criteria / intended outcome satisfied
Related PRs, commits, documentation, or external changes linked where applicable
Resolution is documented by a linked PR that closes the issue, or by a final issue comment explaining what changed, how it was resolved, and how it was verified
Follow-up work split into separate issues where appropriate
Any Forgejo timer is stopped and recorded time is final
Issue moved to Completed and closed

### Type of chore Repository / project maintenance ### What needs to be done and why? Complete the modernization of `.forgejo` as the canonical repository for shared repository templates, synchronization, CI/CD workflows, issue/PR templates, and related automation. The previous overhaul issue accumulated completed work, superseded architectural assumptions, documentation tasks, security work, feature requests, and bug fixes into one large checklist. The repository architecture and project structure have since become clearer. This replacement should remain a **governing issue** for the health of the canonical `.forgejo` automation system while substantial independent work is split into focused child issues. ### Canonical architecture * [ ] Confirm `main` is the canonical source for shared executable/template assets. * [ ] Confirm template branches contain stack-specific template state. * [ ] Confirm managed template repositories are downstream artifacts rather than competing sources of truth. * [ ] Confirm `docs` contains concise standards/reference documentation. * [ ] Confirm the Wiki contains contributor-facing operational guidance. * [ ] Remove stale comments or documentation that contradict this model. ### Shared synchronization * [ ] Audit `sync-config.yml`. * [ ] Confirm all intended shared files are represented. * [ ] Confirm stack-specific assets are not incorrectly treated as shared. * [ ] Confirm directory synchronization works for `ISSUE_TEMPLATE/`. * [ ] Confirm shared-file overwrite behavior. * [ ] Confirm additive/removal behavior is intentional. * [ ] Document the process for intentionally removing previously synced files. * [ ] Test synchronization against a controlled template branch. * [ ] Test synchronization across all template branches. * [ ] Confirm synchronization failures are clear and actionable. ### Template-branch validation * [ ] Inventory every active template branch. * [ ] Define required branch-specific files for each. * [ ] Confirm validation runs before template publication. * [ ] Confirm missing required assets fail validation. * [ ] Confirm invalid shared/template state cannot silently publish. * [ ] Review whether additional structural validation is needed. ### Template publication * [ ] Confirm every template branch maps to the intended template repository. * [ ] Confirm normal publication behavior. * [ ] Confirm fallback PR behavior when direct publication is blocked. * [ ] Confirm publication does not destroy intentional branch-specific state. * [ ] Confirm template repositories are clearly identified as managed. * [ ] Test publication against a disposable or controlled template target. ### Workflow inventory / cleanup * [ ] Inventory every canonical workflow. * [ ] Remove obsolete workflows. * [ ] Confirm workflow names describe their actual behavior. * [ ] Confirm triggers match intended behavior. * [ ] Confirm runner labels match current infrastructure. * [ ] Confirm required tooling is installed rather than assumed. * [ ] Standardize variables versus secrets. * [ ] Standardize handling of workflow tokens. * [ ] Add comments for non-obvious behavior. * [ ] Remove stale references to retired infrastructure. * [ ] Validate high-impact changes through the workflow-validation repository when available. ### Deployment / operations workflows * [ ] Confirm production deployment matches the current architecture. * [ ] Confirm test deployment matches the current architecture. * [ ] Confirm pre/post-deployment validation. * [ ] Confirm rollback orchestration supports stack-specific implementations. * [ ] Link the PHP rollback bug. * [ ] Confirm scheduled health-check behavior. * [ ] Confirm failure notifications are useful and current. ### Releases * [ ] Confirm release trigger behavior. * [ ] Confirm Conventional Commit grouping. * [ ] Confirm breaking-change handling. * [ ] Confirm artifact behavior. * [ ] Confirm release-token requirements and scope. * [ ] Confirm repositories that do not release artifacts are not forced into unnecessary release behavior. ### Canonical issue / PR templates * [ ] Confirm all canonical issue templates match the current issue lifecycle. * [ ] Confirm obsolete `Branch/` label references are removed. * [ ] Link the WIP pull-request workflow issue. * [ ] Link the issue/PR resolution-alignment issue. * [ ] Confirm the final PR template can support both WIP and review-ready PRs. * [ ] Confirm shared contributor templates propagate correctly. * [ ] Confirm templates remain on `main`, not `docs`. ### Repository assets / configuration * [ ] Audit `labels.yml`. * [ ] Decide/document label-provisioning behavior. * [ ] Audit the current configuration-file model. * [ ] Track the eventual `xegames.config` → `xetech.config` migration separately if still desired. * [ ] Confirm canonical reference configuration is distinct from stack-specific defaults. * [ ] Audit reference scripts/stubs. * [ ] Standardize reference-file comments/banners. * [ ] Confirm line-ending rules are intentional. * [ ] Confirm `.editorconfig` / `.gitattributes` behavior. ### Security / protections * [ ] Confirm branch protection on `main`. * [ ] Confirm protection on template branches. * [ ] Confirm CODEOWNERS coverage. * [ ] Confirm synchronization credentials are appropriately scoped. * [ ] Confirm canonical workflows do not receive unnecessary secrets. * [ ] Link host-side and credential-isolation work rather than duplicating it here. ### Documentation alignment * [ ] Confirm `README.md` reflects the current `.forgejo` repository architecture. * [ ] Confirm `WORKFLOW.md` reflects current Git/automation behavior. * [ ] Confirm `ISSUES.md` reflects current lifecycle behavior. * [ ] Confirm `LABELS.md` reflects the current taxonomy. * [ ] Confirm `PULL_REQUESTS.md` reflects current PR behavior. * [ ] Confirm **Completed** terminology is used consistently. * [ ] Confirm `Reviewed/` terminology is used consistently. * [ ] Confirm lifecycle example references use **Example #1–#6** wording. * [ ] Link the governing Wiki issue. * [ ] Split documentation-specific work into the Standards & Documentation project when appropriate. ### Issue decomposition * [ ] Re-evaluate every unfinished item from the old overhaul issue. * [ ] Mark superseded assumptions as intentionally superseded. * [ ] Create focused child issues for independent work. * [ ] Put child issues in the project that actually owns the work. * [ ] Link child issues to this governing issue. * [ ] Avoid allowing this issue to become another unbounded implementation checklist. ### Completion criteria * [ ] Canonical workflows have been audited. * [ ] Template branches have been validated. * [ ] Synchronization and publication have been tested. * [ ] Known independent problems have dedicated issues. * [ ] Current documentation matches actual behavior. * [ ] Current security follow-ups are linked. * [ ] No retired architecture is presented as current. * [ ] A final modernization summary is recorded. ### Technical-debt impact Technical debt in `.forgejo` propagates. Incorrect or duplicated assumptions in the canonical automation system become defaults in future managed repositories, multiplying maintenance cost rather than remaining local. ### Risk / compatibility impact High-impact workflow and template changes can affect many repositories. Develop them on implementation branches, validate against controlled targets, and use explicit review before broad propagation. Changes to the propagation model should be treated carefully when existing managed repositories rely on current behavior. ### Affected branch(es) * `main` — canonical automation and shared templates * template branches — stack-specific template behavior where required * `docs` — separate documentation work only ### Additional context The old umbrella issue had already completed many workflow rewrites but still mixed sync correctness, docs, security, features, and obsolete conventions together. This replacement intentionally uses child issues for independent work while retaining an overall modernization checkpoint. ### Request checklist - [x] I described why this work provides value or avoids future technical debt - [x] I identified known risk, compatibility, or coordination concerns where applicable ### Workflow lifecycle ### Triage - [ ] `Kind/` classification confirmed - [ ] Issue validity reviewed and appropriate `Reviewed/` label assigned - [ ] `Priority/` assigned when appropriate - [ ] Implementation branch referenced on the issue through Forgejo when applicable - [ ] Information requirements resolved; no `Status/Needs More Info` remains - [ ] `Status/Needs Triage` removed before leaving Triage ### Backlog - [ ] Issue is confirmed valid and accepted into the project backlog ### To Do - [ ] Scope and expected outcome are sufficiently defined - [ ] Known prerequisites, dependencies, and required decisions are resolved or understood - [ ] Work has been deliberately selected as upcoming work ### In Progress - [ ] Assignee or active owner identified when appropriate - [ ] Forgejo timer started when time tracking provides meaningful value - [ ] Relevant implementation, research, or work notes recorded as needed - [ ] Forgejo timer stopped when active work ends, pauses, or becomes blocked ### Review Gate - [ ] Review requirement assessed based on complexity, criticality, reversibility, and impact - [ ] If review is required: moved to **In Review** and appropriate testing / validation performed - [ ] If review is required: review comment records what was reviewed, how it was validated, findings, and outcome - [ ] If review is not required: rationale is evident from the low-risk nature of the change ### Completed - [ ] Acceptance criteria / intended outcome satisfied - [ ] Related PRs, commits, documentation, or external changes linked where applicable - [ ] Resolution is documented by a linked PR that closes the issue, or by a final issue comment explaining what changed, how it was resolved, and how it was verified - [ ] Follow-up work split into separate issues where appropriate - [ ] Any Forgejo timer is stopped and recorded time is final - [ ] Issue moved to **Completed** and closed

Xeplosion added the

Rows
Columns

Complete .forgejo canonical automation and template modernization #41