diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 41c72e7..bc929d6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,3 +1,7 @@ +## Problem, rationale, and scope + + + ## What changed @@ -8,7 +12,7 @@ ## API impact and design provenance - + ## Durability and security @@ -16,6 +20,7 @@ ## Checklist +- [ ] The problem, acceptance criteria, and non-goals are recorded here or in a linked design document/Issue. - [ ] Tests cover the changed behavior. - [ ] Public behavior is documented. - [ ] Material external design influences and Mango-owned decisions are recorded. diff --git a/AGENTS.md b/AGENTS.md index 1e3679a..2205565 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,10 @@ pull-request requirements. evolution deliberately: understand what problem a change solves and what was learned from it. This is a research obligation, not a compatibility obligation. +- The normal design workflow starts from Mango's current source, migrations, + OpenAPI, documentation, and executable tests, then compares the analogous + current CMA workflow. Differences are useful design evidence, not an + automatic parity backlog and not a reason to preserve stale Mango behavior. - Before finalizing substantial Mango work that has an analogous CMA workflow, review the current relevant CMA design alongside Mango's implementation and other useful references. Do not wait for CMA, and do not create work merely @@ -54,6 +58,15 @@ pull-request requirements. JSON fields, event types, and public SDK types may be design starting points when they reduce unnecessary invention and fit Mango's workflows. Mango does not need to rename or reshape a sound concept merely to appear different. +- When Mango and CMA solve the same user problem with the same lifecycle, + prefer the same sound high-level design over gratuitous divergence. Exact + field-for-field equality is not a goal: omit hosted rollout details and + fields Mango does not need, and change a field when Mango's self-hosted + semantics require it. +- Prefer standard HTTP semantics, widely understood data shapes, and existing + Mango resource and event primitives. Introduce a Mango-specific header, + wrapper, field, state, or abstraction only when a concrete requirement cannot + be expressed clearly with an established convention or existing primitive. - Once adopted, the resulting surface is owned by Mango. Similarity to CMA does not create compatibility, synchronization, migration, or release-timing obligations. Mango may change, remove, or extend that design directly on @@ -66,7 +79,8 @@ pull-request requirements. - For every material influence, record what Mango adopted, changed, or rejected and why in `docs/provenance.md` or the relevant design document. A CMA change can trigger design review, but it becomes implementation work only after a - Mango user or operator rationale and acceptance criteria exist. + Mango user or operator rationale and acceptance criteria exist in the pull + request, a design document, or an Issue. - Validate the result through Mango's own HTTP, persistence, workflow, recovery, and service tests. Passing a third-party SDK test is optional research evidence, never the definition of success. @@ -74,8 +88,10 @@ pull-request requirements. ## Product-driven development - Mango's documented HTTP API and observable runtime behavior define the - product contract. GitHub Issues define active engineering work and may form a - Mango-specific roadmap. + product contract. GitHub Issues are optional coordination and roadmap tools, + not a prerequisite for implementation. For a solo, short-lived change, the + pull request may carry the problem statement, rationale, acceptance criteria, + and non-goals directly. - `docs/product.md` defines product direction. `docs/capabilities.md` records Mango's current capabilities and limitations; it is not a delta ledger against another service. @@ -96,9 +112,10 @@ pull-request requirements. models, routes, schemas, workflows, or edge cases. Record useful provenance, but make the resulting contract Mango's own, adapt it to the self-hosted trust boundary, and reject constraints that do not serve Mango users. -- Do not add research-preview or vendor-specific surfaces unless a Mango issue - explicitly selects them for an independent product reason. -- Stop when the acceptance criteria and required tests pass. Record adjacent - work as separate Issues instead of expanding the current change. +- Do not add research-preview or vendor-specific surfaces unless the change + explicitly selects them for an independent Mango product reason. +- Stop when the acceptance criteria and required tests pass. Keep adjacent work + out of the current slice; record it in a follow-up PR, design note, or Issue + when coordination or longer-term tracking is useful. - A completed user-visible change must update the affected API documentation, `internal/httpapi/openapi.yaml`, and the capability summary when applicable. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a4c813..d39c94f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,17 +8,21 @@ design starting points when they fit Mango and avoid unnecessary invention. Changes must still preserve a clear line between external design research and Mango's original implementation and product decisions. -## Before opening a change +## Before a substantial change -For substantial API, persistence, or runtime changes, open an issue describing: +Describe the following in the pull request, a design document, or an Issue: - the user-visible problem; - the Mango user or operator rationale and any relevant design references; - the durability, retry, and security implications; - a small independently testable delivery slice. -Small bug fixes and documentation improvements can go directly to a pull -request. +Issues are optional coordination and roadmap tools, not an implementation gate. +For solo development and short-lived work, putting this context directly in the +pull request is preferred over opening an Issue that will immediately close. +Use an Issue when work benefits from discussion, sequencing, ownership, or +longer-term tracking. Small bug fixes and documentation improvements can go +directly to a pull request with proportionate context. ## Development setup @@ -114,11 +118,19 @@ influences and the adopted, changed, or rejected decisions in implementation code or non-public types. An existing third-party client test is optional research evidence, not by itself a reason to preserve an API shape. +When the user problem and lifecycle match, prefer an established CMA design or +another widely used convention over inventing a Mango-only equivalent. Exact +field parity is not required: keep the fields Mango needs, reject hosted or +rollout-only details, and adapt semantics to self-hosting. Prefer standard HTTP, +simple general data shapes, and existing Mango primitives before introducing a +new header, wrapper, state, field, or abstraction. + ## Sandbox backend changes -Open an issue before adding a substantial sandbox backend. Describe the target -use case, trust boundary, host dependencies, network defaults, resource -controls, session persistence, and restart behavior. +Before adding a substantial sandbox backend, describe the target use case, +trust boundary, host dependencies, network defaults, resource controls, session +persistence, and restart behavior in the pull request, a design document, or an +Issue. Backend changes should preserve the provider contract and session-scoped ownership described in the [sandbox backend guide](docs/sandboxes.md). Keep diff --git a/README.md b/README.md index 3f15bf7..85f31e0 100644 --- a/README.md +++ b/README.md @@ -108,8 +108,9 @@ make local-down The [capability summary](https://yanpgwang.github.io/mango/capabilities) states the user-visible boundary. Persistent child-Agent orchestration, provider-neutral Advisor consultations, and shared Session budgets are -implemented; active product work belongs in focused -[GitHub Issues](https://github.com/yanpgwang/mango/issues). +implemented. Active product work may live directly in focused pull requests; +[GitHub Issues](https://github.com/yanpgwang/mango/issues) are used when +discussion, sequencing, or longer-term tracking is useful. ## Architecture diff --git a/docs/architecture.md b/docs/architecture.md index 97f0e38..59747f0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -208,5 +208,6 @@ The strongest current risks are semantic rather than structural: child before primary Workflow and sandbox cleanup. Current API support is tracked in [capabilities and limits](capabilities.md). -[Product direction](product.md) defines how Mango selects work, and focused -engineering belongs in [GitHub Issues](https://github.com/yanpgwang/mango/issues). +[Product direction](product.md) defines how Mango selects work. Focused changes +may be tracked directly in pull requests; Issues remain available when work +needs discussion, sequencing, or longer-term coordination. diff --git a/docs/capabilities.md b/docs/capabilities.md index 17c0a20..333cdac 100644 --- a/docs/capabilities.md +++ b/docs/capabilities.md @@ -81,5 +81,6 @@ PostgreSQL/Temporal/NATS/MinIO/Docker service tests. Mango has not published a versioned release. Published versions will appear in [GitHub Releases](https://github.com/yanpgwang/mango/releases). Follow Mango's [API reference](api/overview.md) for the current wire surface, this page for -operational boundaries, and [GitHub Issues](https://github.com/yanpgwang/mango/issues) -for active work. +operational boundaries, and current +[pull requests](https://github.com/yanpgwang/mango/pulls) or optional +[Issues](https://github.com/yanpgwang/mango/issues) for active work. diff --git a/docs/product.md b/docs/product.md index b2fcc31..81b36d4 100644 --- a/docs/product.md +++ b/docs/product.md @@ -81,7 +81,11 @@ not automatically permanent. During the transition: Mango currently does; - [API reference](api/overview.md) and the served OpenAPI document define the current HTTP surface; -- [GitHub Issues](https://github.com/yanpgwang/mango/issues) hold active Mango - engineering work; -- differences from external contracts are not backlog items unless an Issue - gives them a Mango-specific rationale. +- current source, migrations, documentation, and executable tests are the + starting point for implementation decisions; +- [GitHub pull requests](https://github.com/yanpgwang/mango/pulls), design + documents, and optional [Issues](https://github.com/yanpgwang/mango/issues) + may carry active work and rationale; +- differences from external contracts are design inputs, not backlog items, + unless a Mango change gives them a user or operator rationale and acceptance + criteria. diff --git a/docs/sandboxes.md b/docs/sandboxes.md index 5d25518..b237575 100644 --- a/docs/sandboxes.md +++ b/docs/sandboxes.md @@ -270,5 +270,6 @@ A backend contribution should: - avoid a production or multi-tenant safety claim without evidence and an explicit security review. -Open an issue before a substantial backend integration so the intended use case -and lifecycle implications can be reviewed independently of the adapter code. +Before a substantial backend integration, record the intended use case and +lifecycle implications in the pull request, a design document, or an Issue so +they can be reviewed independently of the adapter code.