XeplosionTechnologies/.forgejo

Watch

Fork

You've already forked .forgejo

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

Establish stack-specific development conventions #39

New issue

Open

opened 2026-09-07 22:26:06 +00:00 by Xeplosion · 0 comments

Xeplosion commented

2026-09-07 22:26:06 +00:00

Owner

Copy link

What question are we trying to answer?

What development conventions should Xeplosion Technologies recommend for each supported language or platform, based on actual project usage, managed templates, upstream tooling, and current engineering practices?

The original convention review focused on a single CONVENTION.md. The documentation model has since changed so stack-specific standards will live in dedicated Wiki pages and should align with the managed template system.

The initial platform set is:

.NET / MonoGame
Node
TypeScript
Python
PHP
Shell / Scripts
Google Sheets

Why does this matter?

Managed templates, CI/CD behavior, technical documentation, and contributor expectations should agree.

Conventions that are arbitrary, outdated, or disconnected from actual projects create unnecessary inconsistency and can cause templates to enforce behavior the organization does not actually want.

The goal is not to create rules for their own sake. It is to establish useful defaults that make projects easier to understand and maintain.

Scope / boundaries

Shared convention structure

Define a common structure for each platform Wiki page.
Separate organization-specific standards from normal upstream language practices.
Identify which conventions are expected versus recommended.
Define how project-specific exceptions should be documented.
Identify which template assets belong to each platform.
Define how each platform page references CI/CD/template documentation.

.NET / MonoGame

Review solution/project layout.
Review namespace conventions.
Review naming conventions.
Review formatting standards.
Review dependency management.
Review testing framework and naming.
Review MonoGame-specific conventions.
Inventory managed template files.
Review CI behavior.

Node

Review Node project layout.
Confirm runtime/version pinning.
Confirm package-manager expectations.
Review formatting/linting.
Review testing expectations.
Inventory managed template files.
Review CI behavior.

TypeScript

Determine where TypeScript guidance differs from Node guidance.
Review project layout.
Review tsconfig defaults.
Review type-checking/strictness expectations.
Review formatting/linting.
Review testing expectations.
Inventory TypeScript-specific template assets.

Python

Review supported Python-version policy.
Review package/project structure.
Review naming.
Review type-hint expectations.
Review Ruff configuration.
Review pytest conventions.
Review pyproject.toml expectations.
Inventory managed template files.
Review CI behavior.

PHP

Review supported PHP-version policy.
Review Composer / PSR-4 structure.
Review naming conventions.
Resolve private-property style.
Review formatting tooling.
Review PHPUnit conventions.
Review web/deployment-specific assumptions.
Inventory managed template files.
Review CI behavior.

Shell / Scripts

Review shebang convention.
Review strict-mode expectations.
Review file naming.
Review executable-bit expectations.
Review shell validation/linting.
Define when logic belongs in scripts versus workflows.
Inventory managed script assets.

Google Sheets

Define when a Sheet is treated as a managed technical artifact.
Review workbook/sheet/table naming where useful.
Establish Apps Script conventions.
Establish formula/documentation expectations.
Establish validation/testing expectations for Apps Script.
Define version-control/export expectations where applicable.
Identify reusable templates or managed reference assets.

Out of scope

Retrofitting every existing repository during this investigation.
Implementing all discovered template changes.
Enforcing arbitrary style where an existing project has a legitimate reason to differ.

Substantial implementation work discovered here should become separate issues.

Definition of done

Every supported platform has been reviewed.
Confirmed conventions are documented.
Unresolved decisions are explicitly identified.
Managed template files are identified.
Testing expectations are defined.
CI/CD integration expectations are defined.
Findings are sufficient to populate the initial platform Wiki pages.
Necessary implementation changes have been split into follow-up issues.
A final investigation summary records the decisions made.

Known sources / starting points

Current .forgejo template branches.
Current managed repositories.
Existing CI/CD workflows and configuration.
Current docs branch.
Current Wiki structure.
Upstream language/tool documentation where no organization-specific decision exists.

Investigation checklist

The research question is specific enough to reach a conclusion
The expected output or decision is defined

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

### What question are we trying to answer? What development conventions should Xeplosion Technologies recommend for each supported language or platform, based on actual project usage, managed templates, upstream tooling, and current engineering practices? The original convention review focused on a single `CONVENTION.md`. The documentation model has since changed so stack-specific standards will live in dedicated Wiki pages and should align with the managed template system. The initial platform set is: * .NET / MonoGame * Node * TypeScript * Python * PHP * Shell / Scripts * Google Sheets ### Why does this matter? Managed templates, CI/CD behavior, technical documentation, and contributor expectations should agree. Conventions that are arbitrary, outdated, or disconnected from actual projects create unnecessary inconsistency and can cause templates to enforce behavior the organization does not actually want. The goal is not to create rules for their own sake. It is to establish useful defaults that make projects easier to understand and maintain. ### Scope / boundaries ### Shared convention structure * [ ] Define a common structure for each platform Wiki page. * [ ] Separate organization-specific standards from normal upstream language practices. * [ ] Identify which conventions are expected versus recommended. * [ ] Define how project-specific exceptions should be documented. * [ ] Identify which template assets belong to each platform. * [ ] Define how each platform page references CI/CD/template documentation. ### .NET / MonoGame * [ ] Review solution/project layout. * [ ] Review namespace conventions. * [ ] Review naming conventions. * [ ] Review formatting standards. * [ ] Review dependency management. * [ ] Review testing framework and naming. * [ ] Review MonoGame-specific conventions. * [ ] Inventory managed template files. * [ ] Review CI behavior. ### Node * [ ] Review Node project layout. * [ ] Confirm runtime/version pinning. * [ ] Confirm package-manager expectations. * [ ] Review formatting/linting. * [ ] Review testing expectations. * [ ] Inventory managed template files. * [ ] Review CI behavior. ### TypeScript * [ ] Determine where TypeScript guidance differs from Node guidance. * [ ] Review project layout. * [ ] Review `tsconfig` defaults. * [ ] Review type-checking/strictness expectations. * [ ] Review formatting/linting. * [ ] Review testing expectations. * [ ] Inventory TypeScript-specific template assets. ### Python * [ ] Review supported Python-version policy. * [ ] Review package/project structure. * [ ] Review naming. * [ ] Review type-hint expectations. * [ ] Review Ruff configuration. * [ ] Review pytest conventions. * [ ] Review `pyproject.toml` expectations. * [ ] Inventory managed template files. * [ ] Review CI behavior. ### PHP * [ ] Review supported PHP-version policy. * [ ] Review Composer / PSR-4 structure. * [ ] Review naming conventions. * [ ] Resolve private-property style. * [ ] Review formatting tooling. * [ ] Review PHPUnit conventions. * [ ] Review web/deployment-specific assumptions. * [ ] Inventory managed template files. * [ ] Review CI behavior. ### Shell / Scripts * [ ] Review shebang convention. * [ ] Review strict-mode expectations. * [ ] Review file naming. * [ ] Review executable-bit expectations. * [ ] Review shell validation/linting. * [ ] Define when logic belongs in scripts versus workflows. * [ ] Inventory managed script assets. ### Google Sheets * [ ] Define when a Sheet is treated as a managed technical artifact. * [ ] Review workbook/sheet/table naming where useful. * [ ] Establish Apps Script conventions. * [ ] Establish formula/documentation expectations. * [ ] Establish validation/testing expectations for Apps Script. * [ ] Define version-control/export expectations where applicable. * [ ] Identify reusable templates or managed reference assets. ### Out of scope * Retrofitting every existing repository during this investigation. * Implementing all discovered template changes. * Enforcing arbitrary style where an existing project has a legitimate reason to differ. Substantial implementation work discovered here should become separate issues. ### Definition of done * [ ] Every supported platform has been reviewed. * [ ] Confirmed conventions are documented. * [ ] Unresolved decisions are explicitly identified. * [ ] Managed template files are identified. * [ ] Testing expectations are defined. * [ ] CI/CD integration expectations are defined. * [ ] Findings are sufficient to populate the initial platform Wiki pages. * [ ] Necessary implementation changes have been split into follow-up issues. * [ ] A final investigation summary records the decisions made. ### Known sources / starting points * Current `.forgejo` template branches. * Current managed repositories. * Existing CI/CD workflows and configuration. * Current `docs` branch. * Current Wiki structure. * Upstream language/tool documentation where no organization-specific decision exists. ### Investigation checklist - [x] The research question is specific enough to reach a conclusion - [x] The expected output or decision is defined ### Workflow lifecycle ### Triage - [x] `Kind/` classification confirmed - [x] Issue validity reviewed and appropriate `Reviewed/` label assigned - [x] `Priority/` assigned when appropriate - [x] Implementation branch referenced on the issue through Forgejo when applicable - [x] Information requirements resolved; no `Status/Needs More Info` remains - [x] `Status/Needs Triage` removed before leaving Triage ### Backlog - [x] 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