From a43ff03cda3da02a97324805c45cd3634b732c7d Mon Sep 17 00:00:00 2001 From: jiangxt2 Date: Thu, 20 Aug 2026 17:38:44 +0800 Subject: [PATCH] docs: add design proposal workflow Signed-off-by: jiangxt2 --- CONTRIBUTING.md | 27 +++++++++ design-docs/README.md | 90 ++++++++++++++++++++++++++++ design-docs/template.md | 128 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 245 insertions(+) create mode 100644 design-docs/README.md create mode 100644 design-docs/template.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1777b21..80d6910 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,6 +40,33 @@ environment and do not install tools implicitly. - Follow the PR template (`.github/PULL_REQUEST_TEMPLATE.md`). - All checks (lint, tests) must pass before merge. +## Design proposals + +Use the [`design-docs/`](design-docs/) process before implementation when a +change affects a public API or persisted contract, crosses component ownership +boundaries, introduces distributed failure or security semantics, adds an +execution engine or extension point, or requires compatibility and migration +decisions. + +Start with a feature issue that establishes the problem and use cases. Changes +to the product boundary use a `[SCOPE]` issue as defined by +[`docs/architecture/product-scope.md`](docs/architecture/product-scope.md). +Then open a draft pull request containing only a proposal copied from +[`design-docs/template.md`](design-docs/template.md) and any supporting images. +Use line comments to review design details and keep unresolved decisions in the +proposal's open-questions section. + +A maintainer must explicitly accept the design before its pull request merges. +Implement the accepted design in a separate pull request and link both records. +Acceptance approves the direction; it does not establish that a capability is +implemented or supported. Update architecture, API, support, and user +documentation when the behavior and its required evidence are delivered. + +A design proposal is normally unnecessary for a contract-preserving bug fix, +local refactor, test addition, or documentation correction. See +[`design-docs/README.md`](design-docs/README.md) for the complete lifecycle, +status rules, review criteria, and document responsibilities. + ## Code Style We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting. Run diff --git a/design-docs/README.md b/design-docs/README.md new file mode 100644 index 0000000..9e1cbb2 --- /dev/null +++ b/design-docs/README.md @@ -0,0 +1,90 @@ +# Design proposals + +This directory contains technical proposals for changes that need architectural +review before implementation. It is part of the contributor workflow, not the +user documentation or the source of truth for implemented capabilities. + +## Document responsibilities + +| Location | Responsibility | +| --- | --- | +| GitHub issues | Establish the problem, use cases, and whether Tributo should address it | +| `design-docs/` | Compare options and review a proposed technical design | +| `docs/adr/` | Record an accepted, durable architectural decision | +| `docs/architecture/` | Describe the architecture implemented by the repository | +| `docs/reference/support-matrix.md` | Record support claims backed by implementation, configuration, and tests | + +## When a proposal is required + +Write a design proposal before implementation when a change does one or more of +the following: + +- adds or changes a public API, persisted configuration, Bundle Manifest, + storage schema, wire protocol, or extension contract; +- changes an execution chain or ownership boundary across Tributo components; +- introduces consistency, concurrency, retry, recovery, streaming-offset, or + credential-security semantics; +- introduces an execution engine, runtime, extension point, or substantial + third-party dependency; +- requires a compatibility, deprecation, or migration plan. + +A proposal is normally unnecessary for a contract-preserving bug fix, local +refactor, test addition, or documentation correction. Maintainers may still +request one when the architectural effect is unclear. + +## Proposal workflow + +1. Open a feature issue that states the problem, use cases, affected components, + and alternatives. Use a `[SCOPE]` issue when the proposal changes the product + boundary defined in + [`docs/architecture/product-scope.md`](../docs/architecture/product-scope.md). +2. Copy [`template.md`](template.md) to + `YYYY-MM-DD-.md` and open a draft pull request containing + the proposal and any supporting images. Do not include production code in + that pull request. +3. Keep the proposal status `Draft` while reviewers discuss the design in pull + request comments. Resolve or explicitly defer every open question. +4. A maintainer records the outcome. Change the status to `Accepted` only after + the maintainer explicitly approves the design. If the proposal establishes a + durable public contract or product boundary, add a concise ADR that links to + the detailed proposal before merging the design pull request. +5. Close rejected or withdrawn proposal pull requests instead of merging their + draft documents. Record an important Go/No-Go outcome in + [`docs/architecture/decision-log.md`](../docs/architecture/decision-log.md) + when it governs future reconsideration. +6. Implement an accepted design in a separate pull request. Link the accepted + proposal and update architecture, support, API, and user documentation only + when the corresponding behavior is implemented and verified. + +Acceptance authorizes the design direction. It does not mean the feature is +implemented, available, or supported. The support matrix remains authoritative +for capability claims. + +## Status values + +| Status | Meaning | +| --- | --- | +| `Draft` | Under review in an open draft pull request; must not be merged | +| `Accepted` | Explicitly approved by a maintainer and eligible to merge | +| `Superseded` | Replaced by a linked, accepted proposal | + +Rejected and withdrawn drafts remain discoverable through their closed pull +requests and related issues. They do not enter the default branch. + +## Review and evolution + +Use pull request line comments for design details and the related issue for +problem-scope discussion. The decider named in the proposal owns the final +outcome. Acceptance requires concrete compatibility and verification criteria, +not only agreement on the happy path. + +An accepted proposal is a historical design record. If implementation requires +a material change to its public contracts, component boundaries, failure +semantics, or acceptance criteria, update the proposal in a new design pull +request and obtain approval before changing the implementation plan. Mark a +replaced proposal `Superseded` and link its successor instead of rewriting the +original rationale without explanation. + +All proposals use English, sentence-case headings without numeric prefixes, and +credential-safe examples. Store images under `design-docs/images//` to +avoid filename collisions. diff --git a/design-docs/template.md b/design-docs/template.md new file mode 100644 index 0000000..7d8bc2b --- /dev/null +++ b/design-docs/template.md @@ -0,0 +1,128 @@ +# Proposal title + +Replace every placeholder in this template before opening the proposal. + +| Attribute | Value | +| --- | --- | +| Status | Draft | +| Authors | GitHub handles | +| Decider | Maintainer GitHub handle | +| Related issue | Issue link | +| Supersedes | None | + +> An accepted proposal approves a design direction. It is not evidence that the +> feature is implemented or supported. Link implemented capability evidence in +> the implementation tracking section. + +## Summary + +Summarize the proposed change and its intended outcome. + +## Motivation and use cases + +Describe the concrete user problem, workload, environment, and scale. Explain +why existing Tributo or Ray capabilities do not solve the problem. + +## Goals + +- Goal + +## Non-goals + +- Explicitly excluded behavior + +## Current behavior and evidence + +Describe the implemented call chain, public contracts, known limitations, and +support evidence that form the baseline. Distinguish implemented behavior from +prototypes, skeletons, and future plans. + +## Proposed design + +Describe the proposed components, control flow, data flow, state transitions, +and ownership boundaries. Identify which work belongs to Tributo, Ray, an +execution engine, or an optional integration package. + +## Public contracts and stability + +List affected public APIs, configuration models, persisted formats, plugin +contracts, manifests, and user-visible errors. Assign an accurate Alpha, Beta, +Stable, or future-planning classification. Explain versioning and compatibility +rules. + +## Failure and security semantics + +Describe validation, fail-closed behavior, retries, idempotency, recovery, +concurrency, resource cleanup, and observability. Explain how credentials and +other sensitive values are resolved, isolated, redacted, and excluded from +persisted identities, logs, representations, and errors. + +Write `Not applicable` with a reason when a concern in this section does not +apply. + +## Compatibility, deprecation, and migration + +Explain compatibility with released APIs and persisted data. Define any +deprecation window, migration mechanism, rollback boundary, and behavior for +old readers, writers, clients, or plugins. + +## Alternatives considered + +For each credible alternative, describe its advantages, risks, and reason for +acceptance or rejection. Include using an existing Ray or third-party feature +and making no change. + +## Test plan and acceptance criteria + +Define independently verifiable acceptance criteria and the evidence required +for each one. Identify unit, contract, conformance, integration, and end-to-end +coverage. Name any required Ray cluster, database, object store, broker, +container, or other real infrastructure gate without claiming it has already +run. + +## Open questions + +- Question and owner + +All blocking questions must be resolved before the proposal becomes +`Accepted`. Explicitly document any deferred question and the boundary that +keeps it from affecting the accepted design. + +## Decision outcome + +Complete this section when the proposal leaves draft review. Record the +decision, decider, rationale, and any follow-up condition. Link a corresponding +ADR or architecture decision-log entry when required. + +## Implementation tracking + +Link implementation issues and pull requests. Link the architecture and support +matrix updates that demonstrate the implemented capability. Do not use proposal +acceptance as implementation evidence. + +## Review checklist + +- [ ] The proposal distinguishes implemented behavior from planned behavior. +- [ ] Goals, non-goals, ownership boundaries, and stability are explicit. +- [ ] Bounded ingestion and unbounded streaming lifecycles remain separate. +- [ ] New bounded sources use Provider and Binding contracts without consumer + source branches. +- [ ] New inference outputs use ResultSink and WriteGateway contracts without a + pipeline-owned data writer. +- [ ] New algorithms declare their AlgorithmSpec, data-loading responsibility, + execution strategy, and Bundle output. +- [ ] Model formats identify exporter, validator, flavor, and loader + responsibilities without format-string guessing. +- [ ] Credential isolation and fail-closed behavior cover success and failure + paths. +- [ ] Compatibility, migration, rollback, and required real-infrastructure + evidence are defined. +- [ ] Support claims require an implementation, configuration entry point, and + corresponding tests. + +Keep unrelated checklist items and append `N/A` with a short reason. Do not +delete them from the proposal. + +## References + +- Source or related design