Merge pull request #289 from adambkaplan/ship-lifecycle-update

feat: Clarify and Simplify SHIP Lifecycle

Author: adambkaplan

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

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: