{"id":30888991,"url":"https://github.com/starisian-technologies/starisian-coding-standards","last_synced_at":"2026-02-11T08:39:54.650Z","repository":{"id":312769326,"uuid":"1048675719","full_name":"Starisian-Technologies/starisian-coding-standards","owner":"Starisian-Technologies","description":"Coding standards for Starisian Technologies and the workflows and actions that enforce them.","archived":false,"fork":false,"pushed_at":"2025-09-01T21:08:44.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"universe","last_synced_at":"2025-09-01T23:22:15.268Z","etag":null,"topics":["agent-installation","code-standards","starisian-technologies"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Starisian-Technologies.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-01T20:54:49.000Z","updated_at":"2025-09-01T21:28:04.000Z","dependencies_parsed_at":"2025-09-07T06:01:24.801Z","dependency_job_id":null,"html_url":"https://github.com/Starisian-Technologies/starisian-coding-standards","commit_stats":null,"previous_names":["starisian-technologies/starisian-coding-standards"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Starisian-Technologies/starisian-coding-standards","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Starisian-Technologies%2Fstarisian-coding-standards","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Starisian-Technologies%2Fstarisian-coding-standards/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Starisian-Technologies%2Fstarisian-coding-standards/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Starisian-Technologies%2Fstarisian-coding-standards/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Starisian-Technologies","download_url":"https://codeload.github.com/Starisian-Technologies/starisian-coding-standards/tar.gz/refs/heads/universe","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Starisian-Technologies%2Fstarisian-coding-standards/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29330081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T06:13:03.264Z","status":"ssl_error","status_checked_at":"2026-02-11T06:12:55.843Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-installation","code-standards","starisian-technologies"],"created_at":"2025-09-08T15:51:17.377Z","updated_at":"2026-02-11T08:39:54.645Z","avatar_url":"https://github.com/Starisian-Technologies.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Starisian WordPress Plugin Coding Standards (v1.1)\n\n**Purpose**\n\nBuild WordPress plugins optimized for global deployment — with emphasis on West Africa (especially The Gambia), mobile‑first UX, limited data environments, and accessibility. Ensure code is maintainable, testable, and resilient offline.\n\n---\n\n## 1) Scope \u0026 Targets\n\n* **WordPress**: 6.4+ (graceful admin‑notice fallback on older).\n\n* **PHP**: 8.2+ (no fatal composer/runtime requirements; bundle vendors if used).\n\n* **Browsers**: Android 8+ baseline; degraded support for older/low‑end (e.g., UC Browser).\n\n* **Networks**: 2G/3G and intermittent connectivity are first‑class constraints.\n\n---\n\n## 2) Architecture \u0026 Namespacing\n\n* **Namespace**: `Starisiansrc…` (PSR‑4).\n\n* **Structure**:\n\n* `plugin-slug.php` (bootstrap, guard checks)\n\n* `src/core/PluginCore.php` (lifecycle, services)\n\n* `src/includes/Autoloader.php` (PSR‑4 fallback if composer not present)\n\n* `assets/` (js, css, images)\n\n* `languages/` (MO/PO, load via `load_plugin_textdomain`)\n\n* **Modular OOP**: services for Admin, Frontend, REST, Shortcodes, Queue, Consent, Telemetry (opt‑in only), etc.\n\n---\n\n## 3) Naming Conventions \u0026 Prefixing (STAR/AIWA)\n\n* **Corporate prefixes**: Use `STAR` (default for shared libraries) or `AIWA` (product‑specific) consistently. All AIWA programming is contracted to Starisian Technologies; copyright notices should attribute **Starisian Technologies** unless otherwise negotiated.\n\n* **One‑word plugin name**: Each plugin defines a **single PascalCase word** (e.g., `Recorder`) as its canonical name. In the bootstrap file, expose it via constants and derive the namespace:\n\n```php\n\n// Canonical identifiers (set once in the main plugin file)\n\nconst STAR_PLUGIN_NAME = 'Recorder'; // One word, PascalCase\n\nconst STAR_PLUGIN_SLUG = strtolower(STAR_PLUGIN_NAME); // 'recorder'\n\nconst STAR_PLUGIN_NS = 'Starisian' . STAR_PLUGIN_NAME; // 'StarisianRecorder'\n\n```\n\nIf not explicitly set, derive `STAR_PLUGIN_NAME` from the directory name: `preg_replace('/[^A-Za-z]/','', basename(__DIR__))`.\n\n* **Namespace root**: `Starisian` mapped PSR‑4 to `src//`.\n\n* **Classes**: `PascalCase` (e.g., `QueueService`, `OfflineStore`). One class per file, filename mirrors class per PSR‑4 (`src/Recorder/QueueService.php`).\n\n* **Methods \u0026 properties**: `camelCase` (e.g., `resumeFromByte`, `chunkSize`).\n\n* **Constants**: `SCREAMING_SNAKE_CASE`, prefixed when global (e.g., `STAR_RECORDER_MAX_CHUNK_BYTES`).\n\n* **Global functions (rare)**: prefix `star_recorder_...()` and mark `@internal`.\n\n* **Actions/filters**: `star-/` (e.g., `star-recorder/queue/started`).\n\n* **REST routes**: `/star-/v1/...`.\n\n* **Options/transients/meta keys**: `star__*`.\n\n* **Assets (script/style handles)**: `star--` (e.g., `star-recorder-queue`).\n\n* **Text domain**: `star-`.\n\n---\n\n## 4) Internationalization (i18n)\n\n* All user‑facing text uses `__()`, `esc_html__()` with a defined text domain.\n\n* Keep strings short, grade‑7 readability; avoid jargon.\n\n* Support multi‑script names (e.g., N’Ko) and diacritics; never strip accents in storage.\n\n---\n\n## 5) Accessibility (WCAG 2.1 AA)\n\n* Semantic HTML; ARIA only to supplement.\n\n* Keyboard support (Tab/Shift+Tab), clear **:focus** styles, visible labels.\n\n* Color contrast ≥ 4.5:1; never convey meaning by color alone.\n\n* Announce async states with ARIA live regions (e.g., “Uploading…”, “Saved offline”).\n\n---\n\n## 6) Performance Budgets (mobile‑first)\n\n* **Per‑page payload**: ≤ 60KB gzipped JS, ≤ 25KB gzipped CSS (target).\n\n* **No heavy front‑end frameworks**; prefer vanilla JS.\n\n* Lazy‑load non‑critical assets; defer/`type=\"module\"` where safe; feature‑detect and progressively enhance.\n\n* Images/SVGs optimized; no webfonts by default (system font stack).\n\n---\n\n## 7) Progressive Enhancement \u0026 Browser Degrade\n\n* Core features must work without JS (submit forms, read content).\n\n* Provide **basic** HTML fallbacks; hydrate with JS for advanced UX.\n\n* Avoid syntax requiring evergreen browsers (transpile if necessary); no arrow‑function/modern syntax in distributed legacy builds.\n\n---\n\n## 8) UX for Low‑Literacy \u0026 Rural Users\n\n* Short labels, large tappable targets (≥ 44×44 px), icon+text buttons.\n\n* Minimal typing; prefer selects, toggles, or guided steps.\n\n* Plain‑language confirmations for record, submit, login, retry.\n\n* Obvious feedback for offline/online state and in‑progress actions.\n\n---\n\n## 9) Data Sensitivity, Consent \u0026 Privacy\n\n* Never expose emails, usernames, or system paths in UI/logs.\n\n* Explicit consent UX for recording, uploads, analytics; **telemetry is opt‑in**.\n\n* Support user data deletion/opt‑out; document data flows (Privacy Policy link).\n\n* Assume shared devices: minimize cookies; provide fallback token flows; short‑lived sessions.\n\n---\n\n## 10) Security\n\n* Capabilities \u0026 nonces on every privileged action.\n\n* Escape on output (`esc_html`, `esc_attr`, `wp_kses`), sanitize on input; parameterize SQL with `$wpdb-\u003eprepare`.\n\n* Validate REST auth; per‑user rate‑limit where appropriate.\n\n* File uploads: validate type/size/MIME; store outside webroot if possible; generate UUID names.\n\n---\n\n## 11) Logging \u0026 Monitoring\n\n* Use `error_log()` **only** behind `WP_DEBUG` and plugin debug flag.\n\n* No PII in logs.\n\n* Surface user‑friendly errors in UI; do not block workflows on analytics/telemetry failures.\n\n---\n\n## 12) Offline‑First \u0026 Staggered Uploads\n\n**Core Principles**\n\n* All interactions (audio, forms, journals) must work offline.\n\n* Cache pending entries in IndexedDB (preferred), falling back to localStorage/FS API.\n\n* Visual indicators: Offline, Queued, Uploading, Paused, Complete.\n\n**Retention**\n\n* Do not delete local data until: (a) confirmed server receipt, (b) user confirms deletion, or (c) retention threshold hit (≥ 30 days, configurable).\n\n**Chunked / Queued Uploads**\n\n* Upload large files in small retryable chunks (FIFO queue).\n\n* On drop: pause, resume from last confirmed byte.\n\n* Allow partial success notices (e.g., “3/5 uploaded”).\n\n* Background Sync if available; otherwise “Try Again” control.\n\n**Client State Model**\n\n* Each entry = UUID + metadata + status: `pending | uploading | complete | failed`.\n\n* Maintain a visible activity log and optional **Export to File** for manual submission.\n\n---\n\n## 13) Plugin Feature Hooks (Extensibility)\n\n* Role‑based feature toggles (filterable).\n\n* User metadata (dialect, contributor status) via dedicated service \u0026 filters.\n\n* Modules: shortcodes, AI form logic, scoring/gamification, queue/consent as independent services.\n\n* All assets enqueued via `wp_enqueue_*` with explicit dependencies and versions.\n\n---\n\n## 14) Dependencies \u0026 Builds\n\n* Avoid runtime Composer dependencies; if needed, **bundle vendor/** and guard runtime.\n\n* NPM builds produce dual outputs: `legacy` (transpiled) and `modern` (module).\n\n* Linting/tooling: PHPCS (WordPress + PSR‑12 rulesets), PHPStan (lvl ≥ 6), ESLint, Stylelint, Markdownlint.\n\n* No network‑fetched code at runtime.\n\n---\n\n## 15) Testing\n\n* **Unit**: PHPUnit with WP test suite.\n\n* **Integration**: REST endpoints, capability checks, nonce flows.\n\n* **E2E**: Playwright (or WP‑env) for offline/queue UX and degraded networks.\n\n* Define fixtures for 2G/3G throttling; include UC/old‑Android smoke tests.\n\n---\n\n## 16) Documentation\n\n* `README.md` with purpose, constraints, budgets, and offline model.\n\n* `CONTRIBUTING.md` (coding style, commit conventions, branching).\n\n* Changelog (Keep a Changelog) and SemVer.\n\n* Admin Help tab or onboarding panel for consent/offline behavior.\n\n---\n\n## 17) Release \u0026 Maintenance\n\n* SemVer releases; database version stored in option with idempotent migrations.\n\n* Safe deactivation/uninstall routines (cleanup options, custom tables behind user confirmation).\n\n* Backward‑compatible filters/actions; mark deprecations with notices and removal timelines.\n\n---\n\n## 18) Acceptance Checklist (Pre‑Merge / Pre‑Release)\n\n* [ ] Meets payload budget (≤ 60KB JS, ≤ 25KB CSS gz).\n\n* [ ] JS‑off flow works for core actions; progressive enhancement verified.\n\n* [ ] Offline queue \u0026 chunked upload pass 2G/3G tests; resume after drop.\n\n* [ ] WCAG 2.1 AA checks: keyboard, focus, labels, contrast.\n\n* [ ] i18n complete; text domain loaded; no hardcoded strings.\n\n* [ ] Security: capabilities, nonces, sanitization, prepared SQL, upload validation.\n\n* [ ] Privacy: consent screens, delete/opt‑out flow, no PII in logs.\n\n* [ ] Admin notices for PHP/WP minimums; graceful disable on failure.\n\n* [ ] Lint/tests green (PHPCS, PHPStan, ESLint, Stylelint, unit/integration/E2E).\n\n* [ ] README/Changelog updated; version bumped; build artifacts committed.\n\n---\n\n## 19) Minimal Bootstrap Guards (Illustrative)\n* On load: check PHP/WP versions; if unmet, add admin notice and early return.\n* Register autoloader (Composer if present; fallback PSR‑4).\n* Instantiate `PluginCore` which wires services (hooks only in runtime, no side effects at include time).\n\n---\n\n## 20) Regional Considerations (West Africa‑First)\n\n* Avoid heavy fonts; rely on system fonts; optional downloadable font pack for extended scripts.\n* Time/number formats localized; avoid hardcoded AM/PM.\n* Content tone: simple, supportive, non‑technical; pictograms alongside text.\n* Keep server endpoints tolerant of brief outages and duplicate submissions (idempotency keys by UUID).\n\n---\n\n## 21) Error Handling\n\n* **Boundary contract**: Public APIs (shortcodes, REST, WP hooks) must return `WP_Error` on failure; internal services may throw exceptions but must be caught at boundaries and translated to user‑safe messages.\n\n* **Retries \u0026 timeouts**: Wrap all network/file I/O in try/catch with capped exponential backoff and jitter; default timeouts ≤ 10s on mobile.\n\n* **Idempotency**: Use UUID‑based idempotency keys for uploads and form posts to deduplicate on retry.\n\n* **User messaging**: Short, translatable messages; never expose PII, stack traces, file paths, or emails.\n\n* **JS error envelope**: Normalize to `{ ok:boolean, code:string, message:string, data?:any }`; offline detection triggers queued retry rather than hard failure.\n\n## 22) Commenting Standards\n\n* **File header**: SPDX license + copyright holder (Starisian Technologies, unless specified), brief purpose, and package tags.\n\n* **PHPDoc**: All public classes/methods/properties require docblocks with `@since`, `@param`, `@return`, and `@throws` as applicable. Document hooks with `@hook` and examples.\n\n* **Translator notes**: Use `/* translators: ... */` before localized strings that need context.\n\n* **Inline comments**: Explain **why**, not what; avoid noise. Keep lines ≤ 100 chars.\n\n## 23) File Structure (PSR‑4 + WP)\n\n```\n\nplugin-slug/\n├─ plugin-slug.php # Bootstrap, guards, constants\n├─ src/\n│ └─ /\n│ ├─ Core/PluginCore.php # Service wiring, lifecycle\n│ ├─ Admin/...\n│ ├─ Frontend/...\n│ ├─ Rest/...\n│ ├─ Services/{Queue,Consent,Storage,...}.php\n│ └─ Support/{Http,Validator,Result}.php\n├─ assets/\n│ ├─ js/{modern,legacy}/...\n│ ├─ css/...\n│ └─ img/...\n├─ templates/ # Escaped view partials (no logic)\n├─ languages/\n├─ tests/{unit,integration,e2e}\n├─ bin/ # Dev scripts (e.g., i18n, build)\n├─ config/{phpcs.xml,phpstan.neon}\n├─ composer.json (optional; vendor/ if bundled)\n└─ README.md, CONTRIBUTING.md, CHANGELOG.md\n\n```\n\n**Rules**: one class per file; no logic on include; side effects only in `PluginCore` hooks. Templates escape output; business logic stays in services.\n\n## 24) Reusable Packages (Composer Add‑ins)\n\n* **Goal**: Migrate generic helpers into versioned Composer packages for reuse across STAR/AIWA plugins.\n\n* **Naming**: `starisian/` (e.g., `starisian/wp-offline-queue`, `starisian/wp-idempotency`). Namespace `StarisianPkgName`.\n\n* **Policy**: No hard runtime Composer requirement—either **bundle vendor/** in the plugin release or feature‑detect and degrade gracefully if the package is absent.\n\n* **Criteria for extraction**: (1) Used by ≥2 plugins, (2) has stable interfaces, (3) test coverage, (4) no project‑specific strings.\n\n* **Release**: SemVer, CHANGELOG, PHPCS/PHPStan gates, minimal deps, security review.\n\n* **Adoption pattern**:\n\n1. Identify helper class candidates (Queue, Storage, Consent, Http, Validator).\n2. Extract to package repo with PSR‑4, add tests and docs.\n3. Publish to GitHub + Packagist (or private registry).\n4. In plugins: require-dev for local builds; for releases, vendor‑bundle or ship a fallback shim.\n\n### Appendix A: Standard Folders (example)\n\n```\n\nplugin-slug/\n\n├─ plugin-slug.php\n├─ src/\n│ ├─ core/PluginCore.php\n│ ├─ includes/Autoloader.php\n│ ├─ admin/\n│ ├─ frontend/\n│ ├─ rest/\n│ └─ services/{Consent,Queue,TelemetryOptIn,...}.php\n├─ assets/{js,css,img}\n├─ languages/\n├─ tests/{unit,integration,e2e}\n├─ README.md\n├─ CONTRIBUTING.md\n└─ composer.json (optional; vendor/ bundled if used)\n\n```\n\n### Appendix B: Commit \u0026 Branching\n\n* Conventional Commits; `main` protected; feature branches via short prefixes (e.g., `feat/queue-retry`).\n\n### Appendix C: Legal \u0026 Licensing\n\n* Include license header (`SPDX-License-Identifier: LicenseRef-Starisian-Technologies-Proprietary`) or GPL as applicable.\n\n* No third‑party code without explicit license file and attribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarisian-technologies%2Fstarisian-coding-standards","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarisian-technologies%2Fstarisian-coding-standards","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarisian-technologies%2Fstarisian-coding-standards/lists"}