From 199022f7f73f67105f088de85c8e2b583670d209 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Mon, 12 Jan 2026 10:51:30 -0500 Subject: [PATCH] feat: Clarify and Simplify SHIP Lifecycle This change proposes to merge the `rejected` and `withdrawn` phases with a `declined` phase. This phase preserves the intent of a feature that the community decided to not implement. To communicate how the lifecycle works, a MermaidJS flowchart has been added, and the markdown content has been restructured to include sub-headers. The `replaced` state has also been updated to communicate that a specific feature has been deprecated or removed. Deprecations and removals require SHIP proposals to ensure the end community is well informed and has sufficient time to stop using the given functionality. Finally, this change also adds a requirement that `implementable` proposals should create corresponding feature tracker issues in GitHub, with sub-issues that identify specific tasks that implement the feature. Tracker issues broadcast to the community work that needs to be done and document the progress of a feature. These tracker issues also encourage contributions from new community members. Assisted-by: Cursor Signed-off-by: Adam Kaplan --- ships/README.md | 97 ++++++++++++++++++++++++------- ships/guidelines/ship-template.md | 2 +- 2 files changed, 76 insertions(+), 23 deletions(-) diff --git a/ships/README.md b/ships/README.md index 80bc793..fdfe22e 100644 --- a/ships/README.md +++ b/ships/README.md @@ -17,28 +17,78 @@ A Shipwright Improvement Proposal (SHIP) is a way to propose, communicate, and c ## SHIP Lifecycle -* **Draft**: SHIPs start their lifecycle as a pull request, copying the proposal template. - They graduate to the _provisional_ or _implementable_ phase when the pull request is merged. -* **Provisional**: SHIPs that reach this phase focus on the _why_. - The objective is to agree that an idea addresses a need for the community. - The summary, motivation, and goals should be clearly articulated. - Drawbacks and alternatives may not need to be identified at this phase, though the community may ask that these be included during review. - Merging a SHIP as provisional does not imply that the community will implement a feature within any reasonable timeframe. -* **Implementable**: SHIPs that reach this phase focus on the _how_. - To graduate to this phase, the proposal needs to provide details on how the feature will be implemented and any new APIs that are introduced. - The proposal must also highlight the risks, drawbacks, and alternatives considered for this feature. - Test and release plans do not need to be fully articulated, though the community may suggest ways to test or release the feature at this stage. - Implementable proposals indicate that the community agrees to a feature and related code can be merged. -* **Implemented**: SHIPs that reach this phase focus on _what_ and _when_. - At this point the feature may have related code pull requests that are under review or merged. - Implemented proposals should have test and release plans identified. - At this point the propsosal is considered "done." - -Other phases in the proposal lifecycle can be: - -* **Rejected**: Used if a provisional or implementable proposal is later rejected by the community. -* **Withdrawn**: Used if the author of a provisional or implementable proposal later withdraws it from consideration. -* **Replaced**: Used if a subsequent proposal is used to implement the same set of functionality. +```mermaid +flowchart LR + Draft ---> Provisional + Draft ---> Implementable + Draft ---> Declined + + Provisional ---> Implementable + Provisional ---> Declined + + Implementable ---> Implemented + Implementable ---> Replaced + + Implemented -.-> Replaced +``` + +### 0. Draft + +SHIPs start their lifecycle as a pull request, copying the proposal template. They graduate to the +_provisional_ or _implementable_ phase when the pull request is merged. + +### 1. Provisional + +SHIPs that reach this phase focus on the _why_: + +- The objective is to agree that an idea addresses a need for the community. +- The summary, motivation, and goals should be clearly articulated. +- Drawbacks and alternatives may not need to be identified at this phase, though the community may + ask that these be included during review. +- Merging a SHIP as provisional does not imply that the community will implement a feature within + any reasonable timeframe. + +### 2. Implementable + +SHIPs that reach this phase focus on the _how_: + +- The proposal needs to provide details on how the feature will be implemented and any new APIs + that are introduced. +- The proposal must also highlight the risks, drawbacks, and alternatives considered for this feature. +- Test and release plans do not need to be fully articulated, though the community may suggest ways + to test or release the feature at this stage. + +Implementable proposals indicate that the community agrees to a feature and related code can be +merged. Once an implementable proposal is accepted, Shipwright project maintainers should do the +following: + +- Create a "feature tracker" GitHub issue in the `community` repository, documenting the desired + functionality and providing links to the relevant SHIP proposal. Feature trackers should link to + sub-issues that target tasks in specific code repositories. See [community#282](https://github.com/shipwright-io/community/issues/282) + for an example feature tracker. +- Add the feature tracker to the project [Roadmap], which communicates that this + approved is approved and seeking contributions. + +### 3. Implemented + +Implemented SHIPs that reach this phase focus on _what_ and _when_: + +- All code and documentation related to the feature should be merged. +- All contributions should be linked to specific releases thorough associated GitHub issues and + pull requests. +- Implemented proposals should have test and release plans identified. + +At this point the propsosal is considered "done." Related feature trackers should be closed in +GitHub and the feature should be marked "done" on the [Roadmap]. Completed features can be removed +frm the [Roadmap] at the discretion of project maintainers. + +### Other Lifecycle Phases + +* **Declined**: Used if the community decides to not implement a feature at any phase of its + lifecycle (outside of `implemented`). `implementable` proposals with code contributions should + not move to the `declined` state. +* **Replaced**: Used if a subsequent proposal is used to implement the same set of functionality, + or is used to deprecate and remove this feature. ## FAQs @@ -59,3 +109,6 @@ You do not have to complete every section of the proposal template - different s **My FAQ isn't answered here!** Open an issue and ask or even better open a PR with a question and proposed answer. + + +[Roadmap]: ./../ROADMAP.md diff --git a/ships/guidelines/ship-template.md b/ships/guidelines/ship-template.md index 85df9dc..4fe9002 100644 --- a/ships/guidelines/ship-template.md +++ b/ships/guidelines/ship-template.md @@ -16,7 +16,7 @@ approvers: - "@oscardoe" creation-date: yyyy-mm-dd last-updated: yyyy-mm-dd -status: provisional|implementable|implemented|rejected|withdrawn|replaced +status: provisional|implementable|implemented|declined|replaced see-also: - "/docs/proposals/this-other-neat-thing.md" replaces: