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: