From e81d2950100c0556cc91397bc1983168824624e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20=C4=8Cert=C3=ADk?= Date: Tue, 7 Jan 2020 08:20:24 -0700 Subject: [PATCH] Update the workflow based on feedback --- WORKFLOW.md | 90 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 53 insertions(+), 37 deletions(-) diff --git a/WORKFLOW.md b/WORKFLOW.md index 47ac9838b..b2ddb233e 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -1,41 +1,57 @@ # Workflow for the Fortran stdlib contributors -This document describes our current workflow. You are welcome to propose -changes in it by opening an -[issue](https://github.com/fortran-lang/stdlib/issues). +This document describes our current workflow. + +We welcome everyone and anyone to participate and propose additions to stdlib. +It is okay if you do not have experience for specification or implementation, +but have an idea for stdlib. If the idea is popular among the community, more +experienced contributors will help it through all 5 steps. + + +1. **Idea**: You have an idea or a proposal. Open an + [issue](https://github.com/fortran-lang/stdlib/issues) to discuss it. This + is on the level of "is there interest in having image reader/writer + functions in stdlib?" The goal of this step is to find out if the community + is interested in having this functionality as part of stdlib. + +2. **API**: When there seems to be significant interest in the proposal (vast + majority of participants think it is a good idea), move on to discuss the + specific API. It's OK to propose the API off the bat if you already have an + idea for it. This step is exploratory and its goal is to find out what the + API should *look* and *feel* like. + +3. **Specification**: Discuss the API and iterate. When there is vast majority + approval for the API, move on to implement it and submit a PR. Small PRs are + always better than large. It is OK to implement only a few functions of a + new module, and continue work on the others in a later PR. All new + functionality goes into an "experimental" namespace + (`stdlib_experimental_*.f90`). As part of the PR, when submitting a new + public facing API, please provide the initial draft of the specification + document as well as the the initial reference implementation of this + specification. The specification is a document that describes the API and + the functionality, so that anyone can use it to create an implementation + from scratch without looking at `stdlib`. The `stdlib` library then provides + the reference implementation. -1. You have an idea or a proposal. Open an issue to discuss it. This is on the - level of "is there interest in having image reader/writer functions in - stdlib?" - -2. When there seems to be significant interest in the proposal, like 80/20 - participants think it's a good/bad idea, move on to discuss the specific - API. It's OK to propose the API off the bat if you already have an idea for - it. - -3. Discuss the API and iterate. When there is ~80/20 approval for the API, move - on to implement it and submit a PR. Small PRs are always better than large. - It's OK to implement only a few functions of a new module, and continue work - on the others in a later PR. All new functionality goes into an - "experimental" namespace (`stdlib_experimental_*.f90`). - As part of the PR, when submitting a new public facing API, please provide - the initial draft of the specification document as well as the the initial - reference implementation of this specification. - The specification is a document that describes the API and the - functionality, so that anyone can use it to create an implementation from - scratch without looking at `stdlib`. The `stdlib` library then provides the - reference implementation. - -4. When opening a PR, request reviews from one or more people that are most - relevant to it. These are likely to be people involved in prior steps of the - workflow. Other contributors (not explicitly invited) are encouraged to - provide reviews and suggestions as well. Iterate until all (or most) - participants are on the same page. We should not merge if there is a strong - objection from the reviewers or from somebody in the wider community. - -5. Moving from experimental to main. The experimental "namespace" contains new - functionality together with its specification. In order to move from - experimental to main, the specification document must be approved by the - wide community and the standards committee (informally). If that happens, - then we can move the code into main, and the particular specification +4. **Implementation** in experimental: When opening a PR, request reviews from + one or more people that are most relevant to it. These are likely to be + people involved in prior steps of the workflow. Other contributors (not + explicitly invited) are encouraged to provide reviews and suggestions as + well. Iterate until all (or most) participants are on the same page. + We can merge when there is vast majority approval of the PR. + +5. **Release**: Moving from experimental to release. The experimental + "namespace" contains new functionality together with its specification. In + order to move from experimental to release, the specification document must + be approved by the wide community and the standards committee (informally). + If that happens, it has now been blessed for broad use and we can move the + code into the main section of `stdlib`, and the particular specification document becomes part of the Fortran Standard Library. + + +Note: the general term "vast majority" above means at least 80%, but ultimately +it is left to our best judgement to ensure that the community agrees that each +PR and proposal was approved by "vast majority". + +You are welcome to propose changes to this workflow by opening an +[issue](https://github.com/fortran-lang/stdlib/issues).