Browse Source

Add MindSpore MEP guidelines in design folder

Signed-off-by: leonwanghui <leon.wanghui@huawei.com>
pull/29/MERGE
leonwanghui 5 years ago
parent
commit
cb377641c1
2 changed files with 311 additions and 0 deletions
  1. +60
    -0
      design/meps/README.md
  2. +251
    -0
      design/meps/XXX-mep-tempate/README.md

+ 60
- 0
design/meps/README.md View File

@@ -0,0 +1,60 @@
# MindSpore Enhancement Proposals (MEPs)

A MindSpore Enhancement Proposal (MEP) is a way to propose, communicate and coordinate on new efforts for the MindSpore project. The MEP guidelines adopted here is heavily
influenced by the [Kubernetes Enhancement Proposals](https://github.com/kubernetes/enhancements/blob/master/keps/README.md) (KEPs) designed by Kubernetes community.

**NOTICE:** *For similar structures some of the same wordings from KEPs are borrowed to adhere to the originally construed meaning.*

## Quick start for the MEP process

1. Socialize an idea with a sponsoring SIG.
Make sure that others think the work is worth taking up and will help review the MEP and any code changes required.
2. Follow the process outlined in the [MEP template](XXX-mep-template/README.md).

## FAQs

### Do I have to use the MEP process?

More or less, yes.

Having a rich set of MEPs in one place will make it easier for people to track
what is going in the community and find a structured historical record.

MEPs are required for most non-trivial changes. Specifically:
* Anything that may be controversial
* Most new features (except the very smallest)
* Major changes to existing features
* Changes that are wide ranging or impact most of the project

Beyond these, it is up to each SIG to decide when they want to use the MEP
process. It should be light-weight enough that MEPs are the default position.

### Why would I want to use the MEP process?

Our aim with MEPs is to clearly communicate new efforts to the MindSpore contributor community.
As such, we want to build a well curated set of clear proposals in a common format with useful metadata.

Benefits to MEP users (in the limit):
* Cross indexing of MEPs so that users can find connections and the current status of any MEP.
* A clear process with approvers and reviewers for making decisions. This will lead to more structured decisions that stick as there is a discoverable record around the decisions.

We are inspired by Kubernetes KEPs, IETF RFCs, Python PEPs and Rust RFCs.

### Do I put my MEP in the root MEP directory or a SIG subdirectory?

Almost all MEPs should go into SIG subdirectories. In very rare cases, such as
MEPs about MEPs, we may choose to keep them in the root.

### What will it take for MEPs to "graduate" out of "beta"?

Things we'd like to see happen to consider MEPs well on their way:
* A set of MEPs that show healthy process around describing an effort and recording decisions in a reasonable amount of time.
* Presubmit checks for MEPs around metadata format and markdown validity.

Even so, the process can evolve. As we find new techniques we can improve our processes.

### What is the number at the beginning of the MEP name?

MEPs are now prefixed with their creation time (eg. yyyy-mm-dd). This gives
both the MEP a unique identifier and provides an easy breadcrumb for people to
find the issue where the current state of the MEP is being updated.

+ 251
- 0
design/meps/XXX-mep-tempate/README.md View File

@@ -0,0 +1,251 @@
<!--
**Note:** When your MEP is complete, all of these comment blocks should be removed.

**Note:** Any PRs to move a MEP to `implementable` or significant changes once
it is marked `implementable` must be approved by each of the MEP approvers.
If any of those approvers is no longer appropriate than changes to that list
should be approved by the remaining approvers and/or the owning SIG.
-->
| title | authors | owning-sig | participating-sigs | status | creation-date | reviewers | approvers | stage | milestone |
| ----- | ------- | ---------- | ------------------ | ------ | ------------- |--------- | --------- | ----- | --------- |
| MEP Template | @leonwanghui | sig-xxx | sig-xxx, sig-yyy | provisional/implementable/implemented/deferred/rejected/withdrawn/replaced | yyyy-mm-dd | TBD | TBD | alpha/beta/stable | alpha: "v0.5", beta: "v0.6", stable: "v1.0" |

# MEP-XXX: Your short, descriptive title

## Table of Contents
<!-- toc -->
- [Summary](#summary)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Proposal](#proposal)
- [User Stories (optional)](#user-stories-optional)
- [Story 1](#story-1)
- [Story 2](#story-2)
- [Notes/Constraints/Caveats (optional)](#notesconstraintscaveats-optional)
- [Risks and Mitigations](#risks-and-mitigations)
- [Design Details](#design-details)
- [Graduation Criteria](#graduation-criteria)
- [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
- [Feature enablement and rollback](#feature-enablement-and-rollback)
- [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning)
- [Monitoring requirements](#monitoring-requirements)
- [Dependencies](#dependencies)
- [Scalability](#scalability)
- [Troubleshooting](#troubleshooting)
- [Implementation History](#implementation-history)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
- [Infrastructure Needed (optional)](#infrastructure-needed-optional)
<!-- /toc -->

## Summary

<!--
This section is incredibly important for producing high quality user-focused
documentation such as release notes or a development roadmap. It should be
possible to collect this information before implementation begins in order to
avoid requiring implementors to split their attention between writing release
notes and implementing the feature itself. MEP editors, SIG Docs, and SIG PM
should help to ensure that the tone and content of the `Summary` section is
useful for a wide audience.

A good summary is probably at least a paragraph in length.

Both in this section and below, follow the guidelines of the [documentation
style guide]. In particular, wrap lines to a reasonable length, to make it
easier for reviewers to cite specific portions, and to minimize diff churn on
updates.

[documentation style guide]: https://gitee.com/mindspore/docs/blob/master/CONTRIBUTING_DOC.md
-->

## Motivation

<!--
This section is for explicitly listing the motivation, goals and non-goals of
this MEP. Describe why the change is important and the benefits to users.
-->

### Goals

<!--
List the specific goals of the MEP. What is it trying to achieve? How will we
know that this has succeeded?
-->

### Non-Goals

<!--
What is out of scope for this MEP? Listing non-goals helps to focus discussion
and make progress.
-->

## Proposal

<!--
This is where we get down to the specifics of what the proposal actually is.
This should have enough detail that reviewers can understand exactly what
you're proposing, but should not include things like API designs or
implementation. The "Design Details" section below is for the real
nitty-gritty.
-->

### User Stories (optional)

<!--
Detail the things that people will be able to do if this MEP is implemented.
Include as much detail as possible so that people can understand the "how" of
the system. The goal here is to make this feel real for users without getting
bogged down.
-->

#### Story 1

#### Story 2

### Notes/Constraints/Caveats (optional)

<!--
What are the caveats to the proposal?
What are some important details that didn't come across above.
Go in to as much detail as necessary here.
This might be a good place to talk about core concepts and how they relate.
-->

### Risks and Mitigations

<!--
What are the risks of this proposal and how do we mitigate. Think broadly.
For example, consider both security and how this will impact the larger
MindSpore ecosystem.
How will security be reviewed and by whom?
How will UX be reviewed and by whom?
Consider including folks that also work outside the SIG or subproject.
-->

## Design Details

<!--
This section should contain enough information that the specifics of your
change are understandable. This may include API specs (though not always
required) or even code snippets. If there's any ambiguity about HOW your
proposal will be implemented, this is the place to discuss them.
-->

### Test Plan

<!--
**Note:** *Not required until targeted at a release.*

Consider the following in developing a test plan for this enhancement:
- Will there be e2e and integration tests, in addition to unit tests?
- How will it be tested in isolation vs with other components?

No need to outline all of the test cases, just the general strategy. Anything
that would count as tricky in the implementation and anything particularly
challenging to test should be called out.

All code is expected to have adequate tests (eventually with coverage
expectations). Please adhere to the [MindSpore contributing guidelines][contributing-guidelines]
when drafting this test plan.

[contributing-guidelines]: https://gitee.com/mindspore/mindspore/blob/master/CONTRIBUTING.md
-->

### Graduation Criteria

<!--
**Note:** *Not required until targeted at a release.*

Define graduation milestones.

These may be defined in terms of API maturity, or as something else. The MEP
should keep this high-level with a focus on what signals will be looked at to
determine graduation.

Consider the following in developing the graduation criteria for this enhancement:
- Maturity levels (`alpha`, `beta`, `stable`)
- Deprecation policy (TBD)

Clearly define what graduation means by either linking to the [API doc definition](https://www.mindspore.cn/api/en/master/index.html), or by redefining what graduation means.

In general, we try to use the same stages (alpha, beta, stable), regardless how the
functionality is accessed.

Below are some examples to consider, in addition to the aforementioned maturity levels.

#### Alpha -> Beta Graduation

- Gather feedback from developers and surveys
- Complete features A, B, C
- Tests are in Testgrid and linked in MEP

#### Beta -> Stable Graduation

- N examples of real world usage
- N installs
- More rigorous forms of testing e.g., downgrade tests and scalability tests
- Allowing time for feedback

**Note:** Generally we also wait at least 2 releases between beta and
GA/stable, since there's no opportunity for user feedback, or even bug reports,
in back-to-back releases.
-->

### Upgrade / Downgrade Strategy

<!--
If applicable, how will the component be upgraded and downgraded? Make sure
this is in the test plan.

Consider the following in developing an upgrade/downgrade strategy for this
enhancement:
- What changes (in invocations, configurations, API use, etc.) is an existing
cluster required to make on upgrade in order to keep previous behavior?
- What changes (in invocations, configurations, API use, etc.) is an existing
cluster required to make on upgrade in order to make use of the enhancement?
-->

## Implementation History

<!--
Major milestones in the life cycle of a MEP should be tracked in this section.
Major milestones might include
- the `Summary` and `Motivation` sections being merged signaling SIG acceptance
- the `Proposal` section being merged signaling agreement on a proposed design
- the date implementation started
- the first MindSpore release where an initial version of the MEP was available
- the version of MindSpore where the MEP graduated to general availability
- when the MEP was retired or superseded
-->

## Drawbacks

<!--
Why should this MEP _not_ be implemented?
-->

## Alternatives

<!--
What other approaches did you consider and why did you rule them out? These do
not need to be as detailed as the proposal, but should include enough
information to express the idea and why it was not acceptable.
-->

## Infrastructure Needed (optional)

<!--
Use this section if you need things from the project/SIG. Examples include a
new subproject, repos requested, github details. Listing these here allows a
SIG to get the process for these resources started right away.
-->

## References (optional)

<!--
Listing some dependencies of `project` and `website` links mentioned in the
sections above if required.
-->

Loading…
Cancel
Save