Add "File-Header-Standards"

2026-05-11 21:32:56 +00:00
parent 0ece2d5dec
commit 6cf9bc108c
1 changed files with 126 additions and 0 deletions
@@ -0,0 +1,126 @@
+[← Back to Home](Home)
+
+# File Header Standards
+
+> Defines the required and optional elements for source file comment headers across all MokoStandards-governed repositories.
+
+---
+
+## Required: Copyright + SPDX
+
+Every source file (PHP, JS, CSS, Shell, YAML) **must** contain a copyright notice and SPDX license identifier within the first 20 lines.
+
+### PHP
+
+```php
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+```
+
+### CSS / JavaScript
+
+```css
+@charset "UTF-8";
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+
+ This file is part of a Moko Consulting project.
+
+ SPDX-License-Identifier: GPL-3.0-or-later
+ */
+```
+
+### YAML (workflows)
+
+```yaml
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+```
+
+### Markdown / HTML
+
+```html
+<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+
+ This file is part of a Moko Consulting project.
+
+ SPDX-License-Identifier: GPL-3.0-or-later
+ -->
+```
+
+---
+
+## Optional: FILE INFORMATION Block
+
+The FILE INFORMATION block provides metadata for tooling (bulk sync, validation, documentation generators). It is **optional** but recommended for key files.
+
+### Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| DEFGROUP | No | Logical group (e.g. `Joomla.Template.Site`) |
+| INGROUP | No | Parent group (e.g. `MokoOnyx`) |
+| REPO | No | Repository URL |
+| PATH | No | File path relative to repo root |
+| BRIEF | No | One-line description of the file |
+
+### Example (PHP)
+
+```php
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: MokoOnyx.Layout
+ * INGROUP: MokoOnyx
+ * PATH: /src/html/layouts/joomla/module/card.php
+ * BRIEF: Card-style module chrome layout
+ */
+```
+
+### Example (YAML)
+
+```yaml
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: MokoStandards.Joomla
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
+# PATH: /templates/workflows/joomla/auto-release.yml.template
+# BRIEF: Joomla build and release pipeline
+```
+
+---
+
+## Removed Fields
+
+| Field | Status | Reason |
+|-------|--------|--------|
+| **VERSION** | **Removed** | Version is tracked in README.md and manifest files (templateDetails.xml, composer.json, etc.), not in individual file headers. Maintaining version numbers in every file header caused drift and unnecessary churn on bulk updates. |
+
+---
+
+## Validation
+
+The `check_license_headers.php` validator checks for the presence of `SPDX-License-Identifier:` in the first 20 lines of tracked PHP, JS, CSS, and Shell files. This is an **advisory** check (always exits 0).
+
+```bash
+php validate/check_license_headers.php --path /a/MokoOnyx
+```
+
+---
+
+## Related
+
+- [Documentation-Standards](Documentation-Standards.-) -- repo health and required files
+- [WORKFLOW_STANDARDS](WORKFLOW_STANDARDS) -- CI/CD workflow conventions