Document workflow based on the discussion in #5

[certik]

No description provided.

[nncarlson]

I think item 5 is an absolute must, but I frankly think that item 4 should be accompanied by at least a draft of the specification. That is the API after all.

[zbeekman]

I like it, and think this is a good starting point that captures the general themes and ideas discussed in #5.

A few questions/food for thought:

• The canonical name for instructions on how to contribute to a repository is CONTRIBUTING.md. Should this document be renamed?
• Where do more mechanical/logistical workflow considerations get documented on the level of:
  • [Github flow] vs [GitFlow] branching & release workflow/models
  • Is it OK to (and when is it OK to):
    • Squash merge
    • Rebase merge
    • Fast forward merge

Basically, I think we should have a CONTRIBUTING.md and need to figure out at some point:

• How is this document distinct, and, if so, what is each document responsible for
• Additional, more logistic workflow/contributing details like fork vs branch, etc.

[certik]

@nncarlson I like your idea that already at step 4. there should be a draft of the specification.

What we can do is to write the specification for open to show how it could be done, and then require it for each new functionality before it gets merged.

[milancurcic]

Thanks for opening this PR, and I agree we should require a spec at step 4. I skimmed through and like what I see so far, but will give detailed read-through and suggestions later tonight.

[certik]

I updated the document to include the specification requirement already in step 3.

[milancurcic]

I like this workflow a lot. I have a few content and wording suggestions. I list them all here because I can't quite get the suggestions to workout for multiline edits.

First, I suggest adding a statement at the beginning that would invite and encourage newcomers (to either stdlib or Fortran) to participate, something like:

"We welcome everyone and anyone to participate and propose additions to stdlib. It's okay if you don't 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."

Use a keyword for each step to make it more memorable. Something like:

1. Idea: ...
2. API: ...
3. Specification: ...
4. Implementation: ...
5. Stabilize: ...

Third, add a sentence to the end of each Step 1 and 2 to describe the key goal of the step (other steps are clear!), I suggest:

1. ... The goal of this step is to find out if the community is interested in having this functionality as part of stdlib.
2. ... This step is exploratory and its goal is to find out what should the API look and feel like.

In Step 5 I suggest using the word "stable" instead of "main". (now you see why I called Step 5 Stabilize)

In Step 4, I suggest instead of this:

We should not merge if there is a strong objection from the reviewers or from somebody in the wider community.

To say:

"We can merge when there is majority approval (4/5) of the PR."

Rationale: We shouldn't have any one person be able to block the PR from going forward if they strongly object. If I don't like the API or implementation but 4 other contributors strongly support it (because to successfully work through Steps 2 and 3 you have to strongly support it), I shouldn't be able to throw a wrench in. Majority support should be good enough for merge here. Step 3 is already quite strict as it requires a majority support for a spec, so in Step 4 we are likely to disagree only about internal implementation.

Please adopt these edits if you like them. I approve this PR either way.

[certik]

Mostly agree. Instead of stabilization, why not to call it standardization? And experimental vs standard.

…

On Mon, Jan 6, 2020, at 5:09 PM, Milan Curcic wrote: ***@***.**** approved this pull request. I like this workflow a lot. I have a few content and wording suggestions. I list them all here because I can't quite get the suggestions to workout for multiline edits. First, I suggest adding a statement at the beginning that would invite and encourage newcomers (to either stdlib or Fortran) to participate, something like: "We welcome everyone and anyone to participate and propose additions to stdlib. It's okay if you don't 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." Use a keyword for each step to make it more memorable. Something like: 1. *Idea*: ... 2. *API*: ... 3. *Specification*: ... 4. *Implementation*: ... 5. *Stabilize*: ... Third, add a sentence to the end of each Step 1 and 2 to describe the key goal of the step (other steps are clear!), I suggest: 1. ... The goal of this step is to find out if the community is interested in having this functionality as part of stdlib. 2. ... This step is exploratory and its goal is to find out what should the API *look* and *feel* like. In Step 5 I suggest using the word "stable" instead of "main". (now you see why I called Step 5 Stabilize) In Step 4, I suggest instead of this: > We should not merge if there is a strong objection from the reviewers or from somebody in the wider community. To say: "We can merge when there is majority approval (4/5) of the PR." Rationale: We shouldn't have any one person be able to block the PR from going forward if they strongly object. If I don't like the API or implementation but 4 other contributors strongly support it (because to successfully work through Steps 2 and 3 you have to strongly support it), I shouldn't be able to throw a wrench in. Majority support should be good enough for merge here. Step 3 is already quite strict as it requires a majority support for a spec, so in Step 4 we are likely to disagree only about internal implementation. Please adopt these edits if you like them. I approve this PR either way. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#94?email_source=notifications&email_token=AAAFAWGGY4QGQKPSXKXU2QTQ4PB4XA5CNFSM4KDI2ML2YY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCQ2ECBI#pullrequestreview-338968837>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWH7ESG62ACZIS3OSATQ4PB4XANCNFSM4KDI2MLQ>.

[milancurcic]

I think "standard" may be confusing, especially if we use the word "Standardize". It sounds a bit too close to "become part of the Fortran Standard". But that's not what we mean because we hope that some of the functions eventually transition from stdlib to the Standard. That would indeed be to "Standardize".

Now, if we mean "standard" as "accepted as part of the standard library", then it implies that experimental is somehow non-standard, or not part of stdlib, which I think it is.

I think it's just inconvenient jargon that there is both a standard and stdlib but they mean different things. What we're really doing here is transition from what everybody else calls "development" -> "stable".

[milancurcic]

I think "Standardize" should be Step 6, 5-10 years in the future :)

[certik]

How would you describe our "stable" section of stdlib? I think we do more than just a regular stable branch from other projects.

…

On Mon, Jan 6, 2020, at 5:52 PM, Milan Curcic wrote: I think "Standardize" should be Step 6, 5-10 years in the future :) — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#94?email_source=notifications&email_token=AAAFAWEL7CUBEZBMQRGF2ETQ4PG4FA5CNFSM4KDI2ML2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIHJUEQ#issuecomment-571382290>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWC3TDRGPZPDYJX36DDQ4PG4FANCNFSM4KDI2MLQ>.

[certik]

For example we will require specification document, which other projects do not.

…

On Mon, Jan 6, 2020, at 6:57 PM, Ondřej Čertík wrote: How would you describe our "stable" section of stdlib? I think we do more than just a regular stable branch from other projects. On Mon, Jan 6, 2020, at 5:52 PM, Milan Curcic wrote: > I think "Standardize" should be Step 6, 5-10 years in the future :) > > — > You are receiving this because you authored the thread. > Reply to this email directly, view it on GitHub > <#94?email_source=notifications&email_token=AAAFAWEL7CUBEZBMQRGF2ETQ4PG4FA5CNFSM4KDI2ML2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIHJUEQ#issuecomment-571382290>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWC3TDRGPZPDYJX36DDQ4PG4FANCNFSM4KDI2MLQ>. >

[nncarlson]

How about "release"? It's been in experimental and now blessed for broad use.

[milancurcic]

I'd describe a feature in stable or main as:

• Has spent some time in experimental
• Has API that is unlikely to change in the future, as agreed on by the community
• Has a specification document
• After getting traction in external projects, is a candidate for proposal to Fortran standard committee

[milancurcic]

I like release also.

[certik]

I am going to go ahead and merge this, as it is good enough, so that we can move on. Let's submit further PRs if somebody has any ideas for improvement.