Repository navigation
Development and Release Workflow
Use versioned source, GitHub issues/PRs, exact commit SHAs, and required Actions as durable shared state. The Wiki explains the system; it does not override tagged documentation, source, or security policy.
| Need | Use |
|---|---|
| Reproducible defect or concrete feature need | GitHub Issue |
| Source, content, schema, installer, or documentation change | Pull Request |
| Portfolio status and priorities | GitHub Project |
| Stable orientation | Wiki |
| Reproducible procedure or sanitized evidence | Repository docs/ / evals/
|
| Vulnerability | Private process in SECURITY.md |
Read AGENTS.md
and CONTRIBUTING.md
before editing. Search existing issues/PRs, confirm the affected surface and
acceptance criteria, and work from current protected main on a focused branch.
Do not push repository changes directly to main.
Runtime changes belong in src/opensocrates/, authored methods in
content/methods/, schemas in schemas/source/, and distribution templates in
plugin-src/<host>/. Shared reader/decision guidance is in plugin-src/shared/.
Regenerate derived outputs from their sources and keep EN/KO semantics aligned.
Do not hand-edit generated files or commit native release binaries.
Run the focused checks appropriate to the change and the source-level suite specified in CONTRIBUTING.md. Native Mac release/package gates and Windows native package/lifecycle checks have separate environments. Record exact commands and results against the reported commit; never report an unrun command as passed. Required live evidence remains distinct from offline CI.
Open incomplete work as Draft. A reviewable PR states the concrete behavior, linked issue or maintenance reason, validation, privacy/rollback impact, evidence level, and remaining limitations. Keep its description current. Merge only when required checks and review conditions are satisfied.
- Freeze the intended source identity and synchronized generated content.
- Pass the applicable source, native build, package, installer, and security gates.
- Assemble the supported Mac/Windows assets, manifests, SBOMs, and checksums.
- Make README, platform guides, changelog, release notes, and support wording agree with the implementation and recorded evidence.
- Publish an immutable tagged GitHub release through the authorized release flow.
- Verify public asset bytes and identities before publishing the matching npm version.
- Synchronize the Wiki and other public entry points with that release.
Publication is separate from a merged PR or successful CI. Account activation, authenticated host delivery, clean-machine acceptance, and useful-result observations retain their actual evidence status; an unavailable application receipt is not a new universal release or task-completion requirement.
Every handoff should state: current commit; completed behavior; exact verified commands/results; checks not run and why; next actions; known limitations. Preserve failures and recovery paths without private user data. The revised v1.5 release builds on the v1.4 Codex foundation; withdrawn PR #95 is historical evidence and must not be merged, cherry-picked, or copied into the new baseline.