Contribution process including Maturity Levels

[maxcapraro]

This pull request proposes a modified contribution process for the patterns working group. It introduces a new maturity model (reusing a lot of what was there already) that serves as a funnel to get contents in a patterns e-book and a (less thoroughly edited) patterns catalogue. Major changes:

• A four stage maturity model for pattern contents (outlined in a contributor-handbook.md)
• A simplified CONTRIBUTING.md reflecting these changes.

My aim was to synthesize the discussions on Slack and in the patterns call a couple weeks ago with @spier, @MaineC, and @lenucksi. My hope is that such a process enables the following:

• Attracting and retaining new contributors

  • Early feeling of success after a merge (in level 1, 2)
  • Simplifies lifecycle of pull requests (many labels, late merges can be discouraging for contributors)
  • Caters to different time invests contributors might be willing to make (contributing a good idea vs. a polished pattern that could become part of a book)

• Have contents in the repository - to find and read - instead of hidden away in pull requests.

• Keep the quality in the repo as high as it currently is by making requirements / expectations explicit.

• Have a workflow that allows us to funnel patterns smoothly to become ready for publishing a patterns catalogue and e-book.

After this PR is merged, we should proceed as follows:

• Leave old labels intact for now but mark with prefix depr and gray color
• Delete old labels (after 90 days)
• Discuss after first experiences if labels for new maturity levels will be needed (no rush! as not information loss to be expected)
• Leave existing patterns in the root folder, migrate pattern by pattern

[spier]

Wow, this look like a substantial amount of work went into this already @maxcapraro !
Even without having read it in detail yet:
Thank you for your contribution! So cool to see this group so active at the moment.

To do it justice, I will read it in the coming days with a fresh mind.

[NewMexicoKid]

Overall, this looks good, but I think my suggested changes should be implemented.

[lenucksi]

Thanks for writing this down in such a nice way and catching the gist of many discussions.
I do give this 👍

(And added a bunch of review comments that can be turned into issues using one of the GitHub features.)

[spier]

@maxcapraro I finally had time to read this. Lots of great starting points in here!

Before providing my own thoughts, a couple of questions to clarify what your intentions are.

• I tried to map the current maturity levels (Donut, Unproven, Proven) to the proposed maturity levels. Would this be roughly correct?
  • Initial = Donut
  • Structured = Unproven
  • Validated = Proven
  • Holy = Proven++ (i.e. a proven pattern that provides even more known instances)
• What is the motivation for introducing an additional level after Proven?
• What is a tale?
• What is the patterns catalogue? Is that this repo itself?

[maxcapraro]

Thank you so much for taking the time :)

I tried to map the current maturity levels (Donut, Unproven, Proven) to the proposed maturity levels. Would this be roughly correct?
Initial = Donut
Structured = Unproven
Validated = Proven
Holy = Proven++ (i.e. a proven pattern that provides even more known instances)

Nope. This is intended to provide a new terminology to discuss the maturity of patterns (and replace the two independent dimensions in use currently).

What is the motivation for introducing an additional level after Proven?

Many of the patterns that would currently fit the maturity validated are of high quality, but not necessary have a) broad community consensus and b) sufficient quality for print.

What is the patterns catalogue? Is that this repo itself?

I'll add explanation to the next iteration of the PR. My suggestion is to provide two types of documents:

• First we aim to create a patterns catalogue (as PDF, gitbook etc.) where we are open in what we include (e.g. we could include structured, validated, established patterns).
• In the longer term, we aim to also provide a (less frequently published) patterns book where we need to achieve higher editing quality and also need to make sure that there is broader community consensus.

What is a tale?

I'll adapt the PR to discuss the different proposed document types. The idea behind a tale: Some folks might want to share an insight, but not have the time to structure it as a pattern or feel that it cannot (yet) be structured as a pattern. My hope is, that we can still collect these materials - in the hope to work with them or reuse them once new materials / insights emerge.

[lenucksi]

Overall, this looks good, but I think my suggested changes should be implemented.

@maxcapraro has addressed and closed your two comments, could you please do another review @NewMexicoKid? I would not like to merge with a standing change requested review.

[maxcapraro]

Requiring 3 instances to become Validated is too strict for me. From reading the patterns that we have today, it looks like the unspoken requirement was that a single Known Instance would make a pattern Proven. We could test this by trying to collect more Known Instance for existing patterns. If we fail to collect 3 instances for the Proven patterns, then we know that requiring 3 instances is too much.

This is a pragmatic approach, that I suggest for everything written in this PR: Let's see how it plays out and adapt quickly where necessary :)

[maxcapraro]

Hello @NewMexicoKid, @lenucksi, @spier, @fwan2000. I (think I) addressed all of your comments. Please signal if this PR is good to go or if I overlooked something :)

[lenucksi]

Hello @NewMexicoKid, @lenucksi, @spier, @fwan2000. I (think I) addressed all of your comments. Please signal if this PR is good to go or if I overlooked something :)

Thanks for adapting the source for the comments. I like them. I still see a few open discussions and would like to work towards resolving them and would love to read about @NewMexicoKid's opinion here.

[maxcapraro]

This reply contains a lot of text, so if we find that we have a hard time resolving this thread in here, I am more than happy to talk about it e.g. in one of the next office hours.

Office hours sounds like a good plan. I feel this PR is stuck. Let's discuss it in the office hours. See this thread: https://innersourcecommons.slack.com/archives/C2EFRTS6A/p1590438603273000

[spier]

This process proposal already resonates a lot better with me. Thanks for the work that you put into this.

I left some specific feedback and suggestions inline.

Overall I propose these changes:

1. adding a top-level folder patterns/, with the 4 folders for the stages below that. This will make it easier to apply automation to all patterns and reduce the number of folders at the top-level.
2. if we could get rid of the different document types donut and tale, that would make things a lot easier. If people want to share a story (tale) even before they would call it pattern/donut, they can already discuss it via a GitHub issue or in Slack. A donut is already represented well by specifying the status in the file itself as Donut.
3. I think we don't need the prefix pattern-* for each file, if we have a top-level folder patterns/ (see point (1)). The prefix would make all file names longer, and we would also have to rename all patterns. Most if not all files are patterns anyways, so the prefix seems redundant.
4. Just out of curiosity, any first thoughts what the difference between basic and advanced style guide would be?

[maxcapraro]

Thank you for this very detailed review once again, @spier :)

I answered inline or directly applied a fix where appropriate.

1. adding a top-level folder patterns/, with the 4 folders for the stages below that. This will make it easier to apply automation to all patterns and reduce the number of folders at the top-level.

Agreed! I'll do that. Done.

2. if we could get rid of the different document types donut and tale, that would make things a lot easier. If people want to share a story (tale) even before they would call it pattern/donut, they can already discuss it via a GitHub issue or in Slack. A donut is already represented well by specifying the status in the file itself as Donut.

In general, I am somewhat ambivalent about dropping (or not) the document types. My main motivations here, were the following:

• Contributing something unstructured to the repo (potentially after a thorough discussion in an issue) creates a quick feeling of success for the contributor
• Contributing something unstructured to the repo persists and makes available that experience (e.g. we could put it into the appendix of our patterns catalogue).
• In the long run, the document types allow us to move away from too much meta information within the files itself.

If @spier, @fwan2000, @lenucksi have strong feelings about it: Let's drop it nonetheless.

1. I think we don't need the prefix pattern-* for each file, if we have a top-level folder patterns/ (see point (1)). The prefix would make all file names longer, and we would also have to rename all patterns. Most if not all files are patterns anyways, so the prefix seems redundant.

This depends primarily on the point discussed above.

1. Just out of curiosity, any first thoughts what the difference between basic and advanced style guide would be?

In the advanced style guide, I'd expect references to how to address our readers, guidelines for usage of passive vs. active voice, grammar regimes (oxford vs. no oxford comma, ...).

In the basic style guide, I'd expect things like: write in full sentences unless its a list, potentially some md-conventions, ...

[lenucksi]

Thank you for this very detailed review once again, @spier :)

Thanks indeed! 😄

1. if we could get rid of the different document types donut and tale, that would make things a lot easier. If people want to share a story (tale) even before they would call it pattern/donut, they can already discuss it via a GitHub issue or in Slack. A donut is already represented well by specifying the status in the file itself as Donut.

In general, I am somewhat ambivalent about dropping (or not) the document types. My main motivations here, were the following:

• Contributing something unstructured to the repo (potentially after a thorough discussion in an issue) creates a quick feeling of success for the contributor

• Contributing something unstructured to the repo persists and makes available that experience (e.g. we could put it into the appendix of our patterns catalogue).

• In the long run, the document types allow us to move away from too much meta information within the files itself.

Just a suggestion:

• I agree that some of the most interesting stories that would classify as "tale" will happen on channels and in issues. Would it possibly make sense to have a bot supporting collection and submission?
• At the same time, having those stories persistently available would be great.
• That way people do not need to make a conscious effort of writing up things and submitting a PR? (Leaving out but acknowledging the need for a solution to the obvious attribution and possble Chatham issues around this for now)

If @spier, @fwan2000, @lenucksi have strong feelings about it: Let's drop it nonetheless.

1. I think we don't need the prefix pattern-* for each file, if we have a top-level folder patterns/ (see point (1)). The prefix would make all file names longer, and we would also have to rename all patterns. Most if not all files are patterns anyways, so the prefix seems redundant.

This depends primarily on the point discussed above.

True, we could also use embedded metadata here, depending on how we want this material to be consumed.

• If the repo is the primary entry point, having something making the status visible from the filename is helpful.
• If we have something rendered as primary entry point, metadata will likely be a better suggestion.

I was hoping that, based on automation, we can soon move over to PDF and website as primary entry points also giving us a bit of structure and classification that way.

1. Just out of curiosity, any first thoughts what the difference between basic and advanced style guide would be?

In the advanced style guide, I'd expect references to how to address our readers, guidelines for usage of passive vs. active voice, grammar regimes (oxford vs. no oxford comma, ...).

In the basic style guide, I'd expect things like: write in full sentences unless its a list, potentially some md-conventions, ...

Sounds good. That is also short enough to move it to a glossary point + link it.

[spier]

Just had a video conference with Max (I know, crazy real-life communication :))
I think we got an idea how to move this forward, and you will all see some updates to this PR in the coming days.

Just to say so much: I think we are very close now! :)

[maxcapraro]

Just had a video conference with Max (I know, crazy real-life communication :))
I think we got an idea how to move this forward, and you will all see some updates to this PR in the coming days.

In the discussion, @spier and I found that most points blocking this PR revolved around maturity level 4: established. A level that will be useful to us in the long run, but probably not in the next months. This is why (see changes to this PR), we propose to move forward without level 4 (and, thus, also without the introducing different document types).

Just to say so much: I think we are very close now! :)

I agree. From my side this is good to go now :)

We both share one worry: Will we become lazy and not question our process anymore, once it is part of our muscle memory? Sebastian had a good idea about this: After this PR is merged, we should discuss criteria to evaluate whether our process is successful (e.g. do we expect a certain number of patterns per level, a certain number of patterns that make the jump, etc.) ...

Changes were addressed :) Pls consider looking through it again.

[spier]

Looks awesome!

[lenucksi]

Just had a video conference with Max (I know, crazy real-life communication :))
I think we got an idea how to move this forward, and you will all see some updates to this PR in the coming days.

In the discussion, @spier and I found that most points blocking this PR revolved around maturity level 4: established. A level that will be useful to us in the long run, but probably not in the next months. This is why (see changes to this PR), we propose to move forward without level 4 (and, thus, also without the introducing different document types).

This sounds great. 🎉

Just to say so much: I think we are very close now! :)

I agree. From my side this is good to go now :)

Excellent, I also do not see any open discussions left. Hence I think I can merge this.

We both share one worry: Will we become lazy and not question our process anymore, once it is part of our muscle memory? Sebastian had a good idea about this: After this PR is merged, we should discuss criteria to evaluate whether our process is successful (e.g. do we expect a certain number of patterns per level, a certain number of patterns that make the jump, etc.) ...

Sounds good. Can either of you @spier or @maxcapraro make a ticket for this?