From 1f56d0deadc3aaa543ec0196c2ff1bca880e4b7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20=C4=8Cert=C3=ADk?= Date: Mon, 6 Jan 2020 12:09:48 -0700 Subject: [PATCH 1/3] Document workflow based on the discussion in #5 --- WORKFLOW.md | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/WORKFLOW.md b/WORKFLOW.md index 8c1672af4..354b33c2d 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -1,5 +1,37 @@ # Workflow for the Fortran stdlib contributors -This document will describe the workflow we'll follow when developing the Fortran stdlib. -It's largely to be discussed and decided. -For now, take a look at the [issues](https://github.com/fortran-lang/stdlib). +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). + +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`). + +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. Once new functionality lands into + "experimental", the next step is to write a "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`. `stdlib` provides the reference implementation. When + this specification document is approved by the wide community and the + standards committee (informally), then we can move the code into main, and + the particular specification document becomes part of the Fortran Standard + Library. From 92926e0fcecd32ce4d4db94a96e862f04024c237 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20=C4=8Cert=C3=ADk?= Date: Mon, 6 Jan 2020 15:01:31 -0700 Subject: [PATCH 2/3] Make the specification requirement part of step 3. --- WORKFLOW.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/WORKFLOW.md b/WORKFLOW.md index 354b33c2d..47ac9838b 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -18,6 +18,13 @@ changes in it by opening an 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 @@ -26,12 +33,9 @@ changes in it by opening an 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. Once new functionality lands into - "experimental", the next step is to write a "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`. `stdlib` provides the reference implementation. When - this specification document is approved by the wide community and the - standards committee (informally), then we can move the code into main, and - the particular specification document becomes part of the Fortran Standard - Library. +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 + document becomes part of the Fortran Standard Library. 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 3/3] 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).