From 10ecec469ac862d4453b6138db4cdc25f7194f71 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Fri, 24 Apr 2020 11:03:26 +0200 Subject: [PATCH 01/27] Dropped meta/publishing.md because it's outdated --- meta/publishing.md | 37 ------------------------------------- 1 file changed, 37 deletions(-) delete mode 100644 meta/publishing.md diff --git a/meta/publishing.md b/meta/publishing.md deleted file mode 100644 index c0e4497c7..000000000 --- a/meta/publishing.md +++ /dev/null @@ -1,37 +0,0 @@ -# Publishing completed patterns to InnerSourceCommons.org - -There are two separate repositories needed for publishing reviewed and accepted patterns: - -* [InnerSourcePatterns][patternsRepo] -* [InnerSourceCommons][commonsRepo] - -## InnerSourcePatterns repository - -This is a private repository where new ideas, donuts and patterns are published -and reviewed by the patterns community **prior to** publishing them on -[innersourcecommons.org][commons]. Inside of this repository we're using the -standard GitHub workflow where we have one main branch - the master branch. -Contributions are done via fork and pull-requests. - -## InnerSourceCommons repository - -This is where finalized patterns will be published **after** they have -been reviewed and accepted by reviewers. Inside of this repository we're -using the standard GitHub workflow where we have one main branch - the master -branch. Contributions are done via fork and pull-requests. This repository -contains the sources for the GitHub pages website for innersourcecommons.org. - - -# Workflow - -1. For each new pattern to be published, a new issue should be created in the [InnerSourcePatterns][patternsRepo] repository - - the issue should contain the _name_ of the pattern and a _link_ to the accepted pattern inside of the [InnerSourcePatterns][patternsRepo] repository -2. Assign the issue to someone who can see the process through ex: a Trusted Committers (TC), community leader, or yourself -3. TBD - we have yet to deal with bringing over a finalized pattern. - - whether we convert the pattern into a PDF, or keep it in markdown and where it lands on [InnerSourceCommons][commonsRepo], is yet to be determined - - - -[commons]: http://innersourcecommons.org -[patternsRepo]: https://github.com/InnerSourceCommons/InnerSourcePatterns -[commonsRepo]: https://github.com/InnerSourceCommons/innersourcecommons.org From b3a52a4772673ac8d2525de48d94e6f4fd0f2ac7 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Fri, 24 Apr 2020 11:24:46 +0200 Subject: [PATCH 02/27] Deleted file explaining meetings - outdated --- meta/meetings.md | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 meta/meetings.md diff --git a/meta/meetings.md b/meta/meetings.md deleted file mode 100644 index 6cc4c435e..000000000 --- a/meta/meetings.md +++ /dev/null @@ -1,14 +0,0 @@ -# Roles, Tasks, and Meetings - -Become involved with the people and communications of Inner Source Patterns: - -* See our [complete list of patterns](/README.md#list-of-patterns) (written, discussed, reviewed so far) -* See Action Items for all who are interested in patterns: - * Add any missing pattern or add new ones anytime - * Add your name if you want to be on the author team. Mark your name in blue if you want to be the coordinator. - * Add your name to the reviewer team if interested in the pattern -* Coordinator role (per pattern): Setup meetings with pattern Authors to work through the patterns. Note the team can use Google docs or any other tool to work on the pattern. However github is the final destination for the patterns. It is recommended that github be kept as up-to-date as possible. Please keep the status and target updated for each pattern in the spreadsheet. -* Every 2-4 weeks (or even sooner if necessary) we will have a meeting with a larger team and review the patterns. Meetings are coordinated through the innersource-commons google group e-mail list and the innersource-commons slack channel. See the [google docs agenda](https://drive.google.com/open?id=1Fb2zsCimPSCdMf88h9w0-hm8sbzQXmDa6o4LpQF2BjA). -* Folks who want to join the InnerSource Patterns group but are new to this please let us know. We can bring you up to speed. - -If you don't have access yet to the google drive shared folder, contact @thyao, @silona or @cedric on the Slack channel. They can add you to the google group. @cedric can ensure you have access to the #innersource-patterns slack channel. From 003483d4fb994b808b667674c0861a6e1fe2b27c Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Fri, 24 Apr 2020 16:02:43 +0200 Subject: [PATCH 03/27] Simplified contributing.md file --- CONTRIBUTING.md | 92 +++++++++---------------------------------------- 1 file changed, 17 insertions(+), 75 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e529a245..2c5c344f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,95 +1,37 @@ -# How to Contribute +# Contributing to the InnerSource Patterns -First, checkout our complete list of patterns: [public GitHub](https://github.com/InnerSourceCommons/InnerSourcePatterns#reviewed-patterns-proven-and-reviewed) OR [Google Doc](https://docs.google.com/spreadsheets/d/17KPZdCoquTnYSj03pX4v2vn8lrSYO_6HK20u1cwaLPg/edit#gid=0) +The goal of the InnerSource patterns working group is to collect, document, and publish InnerSource best practices. To make the best practices easy to comprehend, evaluate, and apply, we codify them in a specific structure - [the patterns format](). More infos on the working group can be found in our [README.md](https://github.com/InnerSourceCommons/InnerSourcePatterns) file. -We encourage beginners seeking answers to jump in by creating `donut` patterns (filling in the problem, context, forces and resulting context fields but leaving the solution blank) as a way of asking the InnerSource Commons community for help (to find a proven solution or to brainstorm things to try). +For this working group to strive, we welcome your contribution - be it small or huge. -Anyone can offer reviews and comments for [in-progress patterns](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls). We encourage experts to pad their experience - these are hoped to become part of an Inner Source handbook one day. -We work together via GitHub, WebEx, Slack, etc. Do not hesitate to join the [#innersourcecommons](https://isc-inviter.herokuapp.com/) or #innersource-patterns Slack channels and ask to be included in the [patterns meetings](/meta/meetings.md) (there is an email list). +## How to Contribute? -Select one of the following ways to contribute, to learn our workflow: +Please consider contributing in the following ways: -* A. [Write a new pattern](#a-writing-a-new-pattern) -* B. [Discuss/Record early ideas](#b-discussing-early-ideas-in-issues) -* C. [Review existing patterns](#c-interacting-with-patterns-reviews) -* D. [Take part in our Meetings and Roles](/meta/meetings.md) <-- link to separate doc +1. **Read & improve existing patterns.** If you want to get started, we encourage you to read through the existing patterns and materials in this repository. Found a misleading phrase or phony grammar? A mistake in the content? Let us know by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new) or directly propose your fix as a pull request. +2. **Review & discuss open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors. -# A. Writing a New Pattern +3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different quality levels for the contents in this repository: First time contributors should aim for quality levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering with the patterns format and following basic writing style conventions). Our [Contributor Handbook](#) discusses the quality levels in more detail and explains how you can contribute your first pattern. -The below steps can be used to create a new pattern. The use-case here is that you have an idea or problem in your head and can confidently fill out the barest of pattern fields (Solution doesn't need to be known). If you are unsure your idea is ready for this, [discuss it in an issue first](#b-discussing-early-ideas-in-issues). +4. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository! -The simplest way to create a pattern is with your browser (see below). -[Like the command-line better? See here for alternate instructions.](/meta/technical-git-howto.md) -Creating a new pattern +## How to get help? -1. Login to GitHub & inside the [patterns web repo](https://github.com/InnerSourceCommons/InnerSourcePatterns), click on the 'Create new file' button -2. Name the file like this example: "project-management-time-pressures.md" -3. Use the [pattern template](https://raw.githubusercontent.com/InnerSourceCommons/InnerSourcePatterns/master/meta/pattern-template.md) to create your new [markdown](/meta/markdown-info.md) file with the description of your fledgling pattern; it does not need to be complete, as you can add to it later -4. Enter a commit message - * If you are asked to 'Commit directly' vs 'Create a new branch', see [branching details](#use-branches-when-creating-new-patterns) below. -5. Propose this new file and then also create a Pull Request (PR) +We are happy to support you in contributing to the InnerSource patterns. You can reach out to us in the following ways: -You're done! This creates a separate branch and creates a Pull Request (PR) all in one fell swoop! PR's are the mechanism we use for our Review process. See next steps in [Interacting with Pattern Reviews](#c-interacting-with-patterns-reviews). +1. *Via Slack.* Join the InnerSource Commons [Slack instance](https://isc-inviter.herokuapp.com/) and enter the `#innersource-patterns` channel there. +2. *During the patterns office hours.* We established a regular cadence of office hours for you to ask questions. You can find out about the next patterns hoffice hours in the calendar at the bottom of [this page](https://innersourcecommons.org/resources/). -## Use Branches When Creating New Patterns -We develop new patterns in branches with the naming convention: -`pattern/`. -If you are asked to 'Commit directly...' vs 'Create a new branch...' +## License of Contributions -* Assure you select **'Create a new branch...'** and name the branch like this example: "pattern/project-management-time-pressures". -* This occurs when writing a new pattern via the web interface (section A above). -* Only [Trusted Committers](/meta/trusted-committers.md) (TC's) are asked this; we are adding most contributors as TC's. +The contents of this repository are licensed under [CC-BY-SA-4.0](LICENSE.md). By contributing to this repository, you grant us (and everyone else for that matter) the right to use your contribution in accordance with that license. -## Other Tips For Submissions +## Code of Conduct -* Place each sentence on a new line. -_GitHub_ allows leaving comments on a line-by-line basis. -Review and comment on the content of submitted text is much easier if there are multiple lines on-which to leave comments. -Sentences on consecutive lines will be collapsed into a single paragraph (like this one) for the final reader of the content. - -# B. Discussing Early Ideas in Issues - -If you feel that you need extra advice when dealing with patterns, please [open an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues). This process is only needed when contributing early ideas that you are uncertain about. - -Here are tips on starting this discussion: - -* [Create a new ticket](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new), add a concise title, and describe your problem. Think about the context of your problem and your expected output. Where do you see this problem most? What is the setup of your business and organization? Do you have opinions/ideas on what causes or leads-to the problem? -* Ask any questions that you are unsure about. Are you unsure if this problem belongs here? Are you unsure on how to frame and explain the problem? -* [Apply the label](https://help.github.com/articles/applying-labels-to-issues-and-pull-requests/) `Early Idea`. Labels can be found in the right column settings. - -After this process, it is our turn to drive you through the pattern creation process. We will help to land your idea and check if there are existing similar patterns. - - - -# C. Interacting with Patterns Reviews - -A pattern is said to be "in-review" or being "Reviewed" when we have a Pull Request with some amount of Pattern detail filled out. We then communally review, and comment-on, and OK these "in-review" patterns. Usually, we first look for a pattern with all the fields filled out, and then go through TWO peer-reviews. - -## Editing a pattern that is in-review -Go ahead, edit away - we can always go back - and we encourage action over discussion. - -How to edit an existing pattern - -## Reviewing a pattern -FIXME Explain how to add review comments and accepting a review. Basically, this is all done through Githubs web GUI around Pull Requests. - -FIXME Give tips for good reviews. We have done both interspersed comments, or pattern-wide advise. Be constructive. If you can fix the problem, [edit the PR](#editing-a-pattern-that-is-in-review) instead of leaving a comment. - -## Our Review Process -Below are the procedural steps in our Review process: - -1. Decide which Maturity level your pattern is in: `Donut (Lacks solution)`, `Unproven`, or `Proven`; these all describe what state the *Solution* is in. -2. Decide which Review Step you are in: Usually `Incomplete` or `Do 1st Review` -3. Reviewers can now use the PR features to comment on the pattern. -4. In most cases, we do two reviews, and the PR's labels should reflect `Do 2nd Review` etc. -5. After reviews are complete, the reviewers or author should Revise and Finalize the pattern, eventually labeling it with `Accepted`. -6. Once a pattern is `Accepted` by the reviewers, one of the [Trusted Committers](/meta/trusted-committers.md) (most authors are by this point) can Merge the PR on Github. This places the .md file into the master branch / root directory. - -## Completed Patterns -When completed patterns (reviewed and accepted) are ready to be published from this InnerSourcePatterns repo to a Gitbook (PDF), [see our separate Publishing instructions](/meta/publishing.md). +We do not yet have a fully formalized code of conduct yet. We expect all contributors to treat each other respectfully and help us to keep this community free of harassment and discrimination. \ No newline at end of file From e2b081fe8aca2a7745fdf8efb329928eb2f03591 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Fri, 24 Apr 2020 16:21:29 +0200 Subject: [PATCH 04/27] Fixes in formatting, links of contributing.md --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c5c344f0..b3069f9d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to the InnerSource Patterns -The goal of the InnerSource patterns working group is to collect, document, and publish InnerSource best practices. To make the best practices easy to comprehend, evaluate, and apply, we codify them in a specific structure - [the patterns format](). More infos on the working group can be found in our [README.md](https://github.com/InnerSourceCommons/InnerSourcePatterns) file. +The goal of the InnerSource patterns working group is to collect, document, and publish InnerSource best practices. To make the best practices easy to comprehend, evaluate, and apply, we codify them in a specific structure - [the patterns format](meta/pattern-template.md). More infos on the working group can be found in our [README.md](README.md) file. For this working group to strive, we welcome your contribution - be it small or huge. @@ -13,7 +13,7 @@ Please consider contributing in the following ways: 2. **Review & discuss open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors. -3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different quality levels for the contents in this repository: First time contributors should aim for quality levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering with the patterns format and following basic writing style conventions). Our [Contributor Handbook](#) discusses the quality levels in more detail and explains how you can contribute your first pattern. +3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different quality levels for the contents in this repository: First time contributors should aim for quality levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering with the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses the quality levels in more detail and explains how you can contribute your first pattern. 4. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository! @@ -22,9 +22,9 @@ Please consider contributing in the following ways: We are happy to support you in contributing to the InnerSource patterns. You can reach out to us in the following ways: -1. *Via Slack.* Join the InnerSource Commons [Slack instance](https://isc-inviter.herokuapp.com/) and enter the `#innersource-patterns` channel there. +1. **Via Slack.** Join the InnerSource Commons [Slack instance](https://isc-inviter.herokuapp.com/) and enter the `#innersource-patterns` channel there. -2. *During the patterns office hours.* We established a regular cadence of office hours for you to ask questions. You can find out about the next patterns hoffice hours in the calendar at the bottom of [this page](https://innersourcecommons.org/resources/). +2. **During the patterns office hours.** We established a regular cadence of office hours for you to ask questions. You can find out about the next patterns hoffice hours in the calendar at the bottom of [this page](https://innersourcecommons.org/resources/). ## License of Contributions From 3ef2e0cdd2c72c009edd47b10706ec408fd09121 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Sun, 26 Apr 2020 18:36:34 +0200 Subject: [PATCH 05/27] Added contributor handbook --- CONTRIBUTING.md | 2 +- meta/contributor-handbook.md | 83 ++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 meta/contributor-handbook.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3069f9d2..8fab16730 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ Please consider contributing in the following ways: 2. **Review & discuss open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors. -3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different quality levels for the contents in this repository: First time contributors should aim for quality levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering with the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses the quality levels in more detail and explains how you can contribute your first pattern. +3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses the maturity levels in more detail and explains how you can contribute your first pattern. 4. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository! diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md new file mode 100644 index 000000000..fb4cc5ea9 --- /dev/null +++ b/meta/contributor-handbook.md @@ -0,0 +1,83 @@ +# Contributor Handbook + +This document lays out a basic guideline of how to write and contribute a new pattern. + +## Maturity Levels + +We defined four maturity levels for patterns: The higher a pattern's maturity level, the more strictly it was validated and the better is its writing. + + +### Maturity Levels Overview + +| \# | Name | Description | Usage | Time to merge | +| ---- | ---- | ---- | ---- | ---- | +| 1 | Initial | Contains an initial pattern idea or what we call a donut (a pattern with missing sections). | Not included in any publications | A few days / weeks | +| 2 | Structured | Contains a complete pattern that it is not properly validated yet (e.g. because it only synthesizes an idea or the experiences from one instead of three organizations). | Included in the patterns catalogue but with a warning | A few days / weeks | +| 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | Included in the patterns catalogue | One or two months | +| 4 | Holy | The pattern is validated, its writing is of "text book" quality, and the community agrees it is responsible to use it as teaching material. | Included in the patterns catalogue and patterns book | As long as it takes | + +To achieve a given maturity level a pattern has to satisfy the requirements for that given maturity level and lower levels. The following sections lay out the requirements per maturity level in detail. + + +### Requirements: Level 1 - Initial + +Patterns (or other documents) of level 1 are stored in the directory `/1-initial`. + +- Document types: + - Patterns (`pattern-*.md`) + - Donuts - patterns without solution or other missing sections (`donut-*.md`) + - Tale - unstructured information in any form (`tale-*.md`) + +- Validation requirements: + - N/A + +- Content requirements: + - The document is readible & comprehensible for other's than the author(s) + - The author(s) contribute the contents according to the [license](../LICENSE.md) & are allowed to do so + - Thoughts and contents by third parties are quoted / referenced explicitly + + +### Requirements: Level 2 - Structured + +Patterns of level 2 are stored in the directory `/2-structured`. + +- Document types: + - Patterns (`pattern-*.md`) + +- Validation requirements: + - N/A + +- Content requirements: + - Complies with [basic style guide](#) - *Oops! We have not yet developed this* + + +### Requirements: Level 3 - Agreed + +Patterns of level 3 are stored in the directory `/3-agreed`. + +- Document types: + - Patterns (`pattern-*.md`) + +- Validation requirements: + - Is validated by at least three known instances + - Or: pattern warrants to still be included (e.g. because validation is not feasible in the foreseeable future) + - Considers all known instances to the best of working group members' knowledge + - Community agreement (via lazy consensus of TCs) on correctness of contents + +- Content requirements: + - Uses & has no conflicts with working group terminology (defined by glossary / implicit usage) - *Oops! We have not yet developed this.* + - Fits & has no conflicts with existing patterns (of this maturity level or higher) + + +### Requirements: Level 4 - Polished + +Patterns of level 4 are stored in the directory `/4-polished`. + +- Document types: + - Patterns (`pattern-*.md`) + +- Validation requirements: + - Complies with [advanced style guide](#) - *Oops! We have not yet developed this.* + - Community agreement (via lazy consensus of TCs) this representing universal truth about InnerSource (using best judgment) and it being responsible to push it out + - Is free of conflicts with other InnerSource Commons learning materials and external InnerSource literature or adresses these conflicts explicitly + \ No newline at end of file From b94d1b902ccc9d6752aab4410b1e32e67f0c5c5a Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Sun, 26 Apr 2020 18:39:22 +0200 Subject: [PATCH 06/27] Fixed faulty link --- meta/contributor-handbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index fb4cc5ea9..86c11e34d 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -33,7 +33,7 @@ Patterns (or other documents) of level 1 are stored in the directory `/1-initial - Content requirements: - The document is readible & comprehensible for other's than the author(s) - - The author(s) contribute the contents according to the [license](../LICENSE.md) & are allowed to do so + - The author(s) contribute the contents according to the [license](../LICENSE.txt) & are allowed to do so - Thoughts and contents by third parties are quoted / referenced explicitly From 7936767d4a1c59660a718f6548ea60f672883e64 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Sun, 26 Apr 2020 18:41:38 +0200 Subject: [PATCH 07/27] Added (obvious) reference to patterns format --- meta/contributor-handbook.md | 1 + 1 file changed, 1 insertion(+) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index 86c11e34d..4b7e39341 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -48,6 +48,7 @@ Patterns of level 2 are stored in the directory `/2-structured`. - N/A - Content requirements: + - Complies with the [patterns format](pattern-template.md) - Complies with [basic style guide](#) - *Oops! We have not yet developed this* From 8109a713fddc80f99a4a1257c2dce27e892cba1d Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Sun, 26 Apr 2020 18:42:04 +0200 Subject: [PATCH 08/27] Dropped pattern states --- meta/pattern-states.md | 51 ------------------------------------------ 1 file changed, 51 deletions(-) delete mode 100644 meta/pattern-states.md diff --git a/meta/pattern-states.md b/meta/pattern-states.md deleted file mode 100644 index 03227bce9..000000000 --- a/meta/pattern-states.md +++ /dev/null @@ -1,51 +0,0 @@ -# Pattern States (New Nomenclature) - -Below shows the nomenclature around the maturity and state that each pattern can be in. Each pattern is either less or more mature (has a solution or doesn't), and goes through a multi-step review process. - -Pattern Maturity and Review Steps as seen on Github - -## Pattern Maturity - -Pattern Maturity describes what **state the Solution is in**. It gives the reader of these InnerSourcePatterns an idea how much they can trust the pattern. - -* A - Donut (Lacks Solution) -* B - Unproven (Ideas) -* C - Proven (Draft) - -## Review Steps - -The **Review Steps** refer to what needs to be done next in the review process. This keeps reviews on track and helps to move the patterns towards the next level of Pattern Maturity. - -* 0 - Incomplete -* 1 - Do 1st Review -* 2 - Needs Revision -* 3 - Do 2nd Review -* 4 - Finalize -* 5 - Accepted - -## Examples - -**Pattern Maturity** and **Review Steps** are used in combination. Therefore the [pull requests][pulls] on this repository often have two labels, one for the maturity of the solution, and one for the phase of the review the pattern is in. - -Some examples to illustrate this: - -* e.g., Donut pattern needing its 1st review -* e.g., Unproven pattern that has been reviewed once and is in need of a revision - -# Explanation of Changes (from 03/2017) - -Context: Some of these fields were renamed from a prior version of our repository. The below describes the changes made. - -I renamed it "Pattern Maturity", because this was formerly not clear to me what a 'Pattern Type' was. It did not speak to the fact that the 3 'types' were levels of how complete or mature the pattern is. - -"Unproven" and "Proven" will take us getting used to, but they explain the maturity-level better than 'Idea' and 'Draft', which both can mean things not intended (Georg, Daniel, and I used them incorrectly multiple times). When these two states were explained on the head wiki page (now on README) it had in parenthesis that their difference was really how proven or unproven the solutions were. So, why not just use the explanation instead of words that can take on arbitrary meanings? - -I kept "Donut" as I tried a couple meaningful names, but it just sounds too catchy/rememberable as Donut. It definitely needs an explanation next to it "(Lacks Solution)" wherever mentioned - when I was new I couldn't figure out the "donut" references. - -The "Review Steps" refer to what needs to be done NEXT. This keeps reviews on track and knowing what comes next. - -The numbering / order helps on GitHub to visualize and keep reviewers on track. The coloring also helps with visualization. [Go check it out live][pulls]. - -"Early Idea" tag is for Issues where very initial or place holder ideas can be placed. "Non-Pattern" can be used for meta Pull Requests such as edits to README.md. - -[pulls]: https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls From ca136c19d3453ef78a7cdfc44e2c68b517be453c Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Sun, 26 Apr 2020 19:42:21 +0200 Subject: [PATCH 09/27] Made patterns lifecycle more explicit --- meta/contributor-handbook.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index 4b7e39341..db28b848d 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -6,8 +6,7 @@ This document lays out a basic guideline of how to write and contribute a new pa We defined four maturity levels for patterns: The higher a pattern's maturity level, the more strictly it was validated and the better is its writing. - -### Maturity Levels Overview +### In a Nutshell | \# | Name | Description | Usage | Time to merge | | ---- | ---- | ---- | ---- | ---- | @@ -16,6 +15,10 @@ We defined four maturity levels for patterns: The higher a pattern's maturity le | 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | Included in the patterns catalogue | One or two months | | 4 | Holy | The pattern is validated, its writing is of "text book" quality, and the community agrees it is responsible to use it as teaching material. | Included in the patterns catalogue and patterns book | As long as it takes | +For the first pattern you contribute, you should aim for maturity levels `1: initial` or `2: structured`. + +If you want to help promoting a pattern one maturity level up, we suggest to first `create an issue` to discuss the matter and see if someone else is working on that already. After that, you can create a pull request with the necessary changes. + To achieve a given maturity level a pattern has to satisfy the requirements for that given maturity level and lower levels. The following sections lay out the requirements per maturity level in detail. @@ -63,11 +66,12 @@ Patterns of level 3 are stored in the directory `/3-agreed`. - Is validated by at least three known instances - Or: pattern warrants to still be included (e.g. because validation is not feasible in the foreseeable future) - Considers all known instances to the best of working group members' knowledge - - Community agreement (via lazy consensus of TCs) on correctness of contents + - Community agreement (via lazy consensus of trusted committers) on correctness of contents - Content requirements: - Uses & has no conflicts with working group terminology (defined by glossary / implicit usage) - *Oops! We have not yet developed this.* - Fits & has no conflicts with existing patterns (of this maturity level or higher) + - Thorough review by at least two trusted committers ### Requirements: Level 4 - Polished @@ -79,6 +83,6 @@ Patterns of level 4 are stored in the directory `/4-polished`. - Validation requirements: - Complies with [advanced style guide](#) - *Oops! We have not yet developed this.* - - Community agreement (via lazy consensus of TCs) this representing universal truth about InnerSource (using best judgment) and it being responsible to push it out + - Community agreement (via lazy consensus of trusted committers) this representing universal truth about InnerSource (using best judgment) and it being responsible to push it out - Is free of conflicts with other InnerSource Commons learning materials and external InnerSource literature or adresses these conflicts explicitly \ No newline at end of file From 819447c591c8b49a4d0ae2c1e370a2e6f4e0cfea Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Sun, 26 Apr 2020 19:43:38 +0200 Subject: [PATCH 10/27] Minor changes to formatting --- meta/contributor-handbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index db28b848d..f59de3d1b 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -17,7 +17,7 @@ We defined four maturity levels for patterns: The higher a pattern's maturity le For the first pattern you contribute, you should aim for maturity levels `1: initial` or `2: structured`. -If you want to help promoting a pattern one maturity level up, we suggest to first `create an issue` to discuss the matter and see if someone else is working on that already. After that, you can create a pull request with the necessary changes. +If you want to help promoting a pattern one maturity level up, we suggest to first create an issue to discuss the matter and see if someone else is working on that already. After that, you can create a pull request with the necessary changes. To achieve a given maturity level a pattern has to satisfy the requirements for that given maturity level and lower levels. The following sections lay out the requirements per maturity level in detail. From 31e22c9055d41e8386b304a2d82bde757254a5fc Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Tue, 28 Apr 2020 08:53:02 +0200 Subject: [PATCH 11/27] Replaced 'holy' with 'established' --- meta/contributor-handbook.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index f59de3d1b..e670b4ca1 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -13,7 +13,7 @@ We defined four maturity levels for patterns: The higher a pattern's maturity le | 1 | Initial | Contains an initial pattern idea or what we call a donut (a pattern with missing sections). | Not included in any publications | A few days / weeks | | 2 | Structured | Contains a complete pattern that it is not properly validated yet (e.g. because it only synthesizes an idea or the experiences from one instead of three organizations). | Included in the patterns catalogue but with a warning | A few days / weeks | | 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | Included in the patterns catalogue | One or two months | -| 4 | Holy | The pattern is validated, its writing is of "text book" quality, and the community agrees it is responsible to use it as teaching material. | Included in the patterns catalogue and patterns book | As long as it takes | +| 4 | Established | The pattern is validated, its writing is of "text book" quality, and the community agrees it is responsible to use it as teaching material. | Included in the patterns catalogue and patterns book | As long as it takes | For the first pattern you contribute, you should aim for maturity levels `1: initial` or `2: structured`. @@ -74,9 +74,9 @@ Patterns of level 3 are stored in the directory `/3-agreed`. - Thorough review by at least two trusted committers -### Requirements: Level 4 - Polished +### Requirements: Level 4 - Established -Patterns of level 4 are stored in the directory `/4-polished`. +Patterns of level 4 are stored in the directory `/4-established`. - Document types: - Patterns (`pattern-*.md`) From 05e781fa993e504757f222b34068e7cbd5c98611 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Thu, 7 May 2020 16:48:55 +0200 Subject: [PATCH 12/27] Update meta/contributor-handbook.md --- meta/contributor-handbook.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index e670b4ca1..9fbaefc25 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -48,7 +48,8 @@ Patterns of level 2 are stored in the directory `/2-structured`. - Patterns (`pattern-*.md`) - Validation requirements: - - N/A + - Is partially validated by at least one known instance + - Or: pattern warrants to still be included (e.g. because validation is not feasible in the foreseeable future) - Content requirements: - Complies with the [patterns format](pattern-template.md) @@ -85,4 +86,4 @@ Patterns of level 4 are stored in the directory `/4-established`. - Complies with [advanced style guide](#) - *Oops! We have not yet developed this.* - Community agreement (via lazy consensus of trusted committers) this representing universal truth about InnerSource (using best judgment) and it being responsible to push it out - Is free of conflicts with other InnerSource Commons learning materials and external InnerSource literature or adresses these conflicts explicitly - \ No newline at end of file + From 401c5aa9dca937b4a4d1d00e68b551e97af897b0 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Thu, 21 May 2020 15:30:49 +0200 Subject: [PATCH 13/27] Added to contributing.md invitation to discuss via issues --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8fab16730..2e0077cdb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ Please consider contributing in the following ways: 2. **Review & discuss open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors. -3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses the maturity levels in more detail and explains how you can contribute your first pattern. +3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses all this in more detail. You don't feel ready yet to contribute a new pattern? Please start a discussion by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new). 4. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository! From 7be4364e62d15a9ff42309cb362625b82fc29bd5 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Thu, 21 May 2020 15:43:30 +0200 Subject: [PATCH 14/27] Raised requirements for validation based on recommendations by @newmexicokid --- meta/contributor-handbook.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index 9fbaefc25..acc9ba213 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -48,8 +48,8 @@ Patterns of level 2 are stored in the directory `/2-structured`. - Patterns (`pattern-*.md`) - Validation requirements: - - Is partially validated by at least one known instance - - Or: pattern warrants to still be included (e.g. because validation is not feasible in the foreseeable future) + - Is validated by at least one known instance + - Alternatively: key elements of the pattern have been validated in separate contexts and, in consequence, it is justified to believe the full solution will function - Content requirements: - Complies with the [patterns format](pattern-template.md) @@ -65,7 +65,6 @@ Patterns of level 3 are stored in the directory `/3-agreed`. - Validation requirements: - Is validated by at least three known instances - - Or: pattern warrants to still be included (e.g. because validation is not feasible in the foreseeable future) - Considers all known instances to the best of working group members' knowledge - Community agreement (via lazy consensus of trusted committers) on correctness of contents From b47f00fdb1c06459a6f932f474af68d3fa097ac4 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Thu, 21 May 2020 16:18:33 +0200 Subject: [PATCH 15/27] Dropped 'usage'column from overview table --- meta/contributor-handbook.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index acc9ba213..e414d443b 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -8,12 +8,12 @@ We defined four maturity levels for patterns: The higher a pattern's maturity le ### In a Nutshell -| \# | Name | Description | Usage | Time to merge | -| ---- | ---- | ---- | ---- | ---- | -| 1 | Initial | Contains an initial pattern idea or what we call a donut (a pattern with missing sections). | Not included in any publications | A few days / weeks | -| 2 | Structured | Contains a complete pattern that it is not properly validated yet (e.g. because it only synthesizes an idea or the experiences from one instead of three organizations). | Included in the patterns catalogue but with a warning | A few days / weeks | -| 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | Included in the patterns catalogue | One or two months | -| 4 | Established | The pattern is validated, its writing is of "text book" quality, and the community agrees it is responsible to use it as teaching material. | Included in the patterns catalogue and patterns book | As long as it takes | +| \# | Name | Description | Time to merge | +| ---- | ---- | ---- | ---- | +| 1 | Initial | Contains an initial pattern idea or what we call a donut (a pattern with missing sections). | A few days / weeks | +| 2 | Structured | Contains a complete pattern that it is not properly validated yet (e.g. because it only synthesizes an idea or the experiences from one instead of three organizations). | A few days / weeks | +| 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | One or two months | +| 4 | Established | The pattern is validated, its writing is of "text book" quality, and the community agrees it is responsible to use it as teaching material. | As long as it takes | For the first pattern you contribute, you should aim for maturity levels `1: initial` or `2: structured`. From aa05c0bf038bc75d4f748cdc7ba1227ba586e85b Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Thu, 21 May 2020 16:20:42 +0200 Subject: [PATCH 16/27] Fixed broken links --- meta/contributor-handbook.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index e414d443b..84481118f 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -53,7 +53,7 @@ Patterns of level 2 are stored in the directory `/2-structured`. - Content requirements: - Complies with the [patterns format](pattern-template.md) - - Complies with [basic style guide](#) - *Oops! We have not yet developed this* + - Complies with *basic style guide*(#) - *Oops! We have not yet developed this* ### Requirements: Level 3 - Agreed @@ -82,7 +82,7 @@ Patterns of level 4 are stored in the directory `/4-established`. - Patterns (`pattern-*.md`) - Validation requirements: - - Complies with [advanced style guide](#) - *Oops! We have not yet developed this.* + - Complies with *advanced style guide*(#) - *Oops! We have not yet developed this.* - Community agreement (via lazy consensus of trusted committers) this representing universal truth about InnerSource (using best judgment) and it being responsible to push it out - Is free of conflicts with other InnerSource Commons learning materials and external InnerSource literature or adresses these conflicts explicitly From b7001bd7f2eed6d948fc2ae54b186c6a4e5a6bcb Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Thu, 21 May 2020 16:25:21 +0200 Subject: [PATCH 17/27] Droped link to meetings --- README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/README.md b/README.md index 0f797441c..2bb2b01b8 100644 --- a/README.md +++ b/README.md @@ -91,11 +91,7 @@ The pattern form is useful for describing proven patterns but it can also be use # How to Contribute? -[See our CONTRIBUTING.md for details on getting involved](CONTRIBUTING.md) - -We encourage beginners seeking answers to jump in by creating ''donuts'' (problems without solutions). We encourage experts to pad their experience - these are hoped to become part of a book one day. Anyone can offer reviews and comments for [in-progress patterns](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls). - -We work together via Github, Webex, Slack, etc. Do not hesitate to join the [#innersourcecommons](https://isc-inviter.herokuapp.com/) or #innersource-patterns slack channels and ask to be included in the [patterns meetings](/meta/meetings.md) (there is an email list). +We welcome your contribution - be it small or huge! To learn more about how you can become a contributor, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file. # Pattern Meta Info From 626f66a56da20d94fd8c3fd534c4e87d8234e599 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Thu, 21 May 2020 16:45:37 +0200 Subject: [PATCH 18/27] Added directories for maturity levels --- 1-initial/.gitkeep | 0 2-structured/.gitkeep | 0 3-validated/.gitkeep | 0 4-established/.gitkeep | 0 4 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 1-initial/.gitkeep create mode 100644 2-structured/.gitkeep create mode 100644 3-validated/.gitkeep create mode 100644 4-established/.gitkeep diff --git a/1-initial/.gitkeep b/1-initial/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/2-structured/.gitkeep b/2-structured/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/3-validated/.gitkeep b/3-validated/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/4-established/.gitkeep b/4-established/.gitkeep new file mode 100644 index 000000000..e69de29bb From 44fb228ae0478e1fdfe66cc2f7954469d475e2a8 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Mon, 25 May 2020 19:03:46 +0200 Subject: [PATCH 19/27] Update CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e0077cdb..d2a8d7162 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ We are happy to support you in contributing to the InnerSource patterns. You can 1. **Via Slack.** Join the InnerSource Commons [Slack instance](https://isc-inviter.herokuapp.com/) and enter the `#innersource-patterns` channel there. -2. **During the patterns office hours.** We established a regular cadence of office hours for you to ask questions. You can find out about the next patterns hoffice hours in the calendar at the bottom of [this page](https://innersourcecommons.org/resources/). +2. **During the patterns office hours.** We established a regular cadence of office hours for you to ask questions. You can find out about the next patterns office hours in the calendar at the bottom of [this page](https://innersourcecommons.org/resources/). ## License of Contributions @@ -34,4 +34,4 @@ The contents of this repository are licensed under [CC-BY-SA-4.0](LICENSE.md). B ## Code of Conduct -We do not yet have a fully formalized code of conduct yet. We expect all contributors to treat each other respectfully and help us to keep this community free of harassment and discrimination. \ No newline at end of file +We do not yet have a fully formalized code of conduct yet. We expect all contributors to treat each other respectfully and help us to keep this community free of harassment and discrimination. From a7849d68936cecf28bf6f4bdf1b7769faa56ffed Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Mon, 25 May 2020 19:25:57 +0200 Subject: [PATCH 20/27] Added invitation to contribute early stage thoughts and ideas --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d2a8d7162..d248383a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,18 +9,20 @@ For this working group to strive, we welcome your contribution - be it small or Please consider contributing in the following ways: -1. **Read & improve existing patterns.** If you want to get started, we encourage you to read through the existing patterns and materials in this repository. Found a misleading phrase or phony grammar? A mistake in the content? Let us know by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new) or directly propose your fix as a pull request. +1. **Share your thoughts & spark discussion**. A fresh perspective, an intersting thought, or an early novel idea can spark discussions and yield unforeseeable results. We invite you to share your thoughts on InnerSource-related topics at any time by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new), [via Slack, or our patterns office hours](#how-to-get-in-touch). -2. **Review & discuss open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors. +2. **Read & improve existing patterns.** If you want to get started, we encourage you to read through the existing patterns and materials in this repository. Found a misleading phrase or phony grammar? A mistake in the content? Let us know by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new) or directly propose your fix as a pull request. -3. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses all this in more detail. You don't feel ready yet to contribute a new pattern? Please start a discussion by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new). +3. **Review open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors. -4. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository! +4. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses all this in more detail. You don't feel ready yet to contribute a new pattern? Please start a discussion by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new). +5. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository! -## How to get help? -We are happy to support you in contributing to the InnerSource patterns. You can reach out to us in the following ways: +## How to get in touch? + +We are happy to support you in contributing to the InnerSource patterns or to just chat with you. You can reach out to us in the following ways: 1. **Via Slack.** Join the InnerSource Commons [Slack instance](https://isc-inviter.herokuapp.com/) and enter the `#innersource-patterns` channel there. From dd45bd3cdb75a841a45fa8f676de44beb3d7fbb8 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Tue, 2 Jun 2020 12:07:02 +0200 Subject: [PATCH 21/27] Update meta/contributor-handbook.md Co-authored-by: Sebastian Spier --- meta/contributor-handbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index 84481118f..ca222fce5 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -13,7 +13,7 @@ We defined four maturity levels for patterns: The higher a pattern's maturity le | 1 | Initial | Contains an initial pattern idea or what we call a donut (a pattern with missing sections). | A few days / weeks | | 2 | Structured | Contains a complete pattern that it is not properly validated yet (e.g. because it only synthesizes an idea or the experiences from one instead of three organizations). | A few days / weeks | | 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | One or two months | -| 4 | Established | The pattern is validated, its writing is of "text book" quality, and the community agrees it is responsible to use it as teaching material. | As long as it takes | +| 4 | Established | The writing of the pattern is of "text book" quality. The community agrees to use this pattern as InnerSource teaching material. | As long as it takes | For the first pattern you contribute, you should aim for maturity levels `1: initial` or `2: structured`. From aa1d931f17bfd7b39a7c6e0d0c60f38cad541abe Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Tue, 2 Jun 2020 12:11:38 +0200 Subject: [PATCH 22/27] Applied consistent naming of stage 'validated' proposed by @spier --- meta/contributor-handbook.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index ca222fce5..ffd3d0e23 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -56,9 +56,9 @@ Patterns of level 2 are stored in the directory `/2-structured`. - Complies with *basic style guide*(#) - *Oops! We have not yet developed this* -### Requirements: Level 3 - Agreed +### Requirements: Level 3 - Validated -Patterns of level 3 are stored in the directory `/3-agreed`. +Patterns of level 3 are stored in the directory `/3-validated`. - Document types: - Patterns (`pattern-*.md`) From d1db6f8fa631573165c5fec30bbd6f9eea51862b Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Tue, 2 Jun 2020 12:15:28 +0200 Subject: [PATCH 23/27] Update meta/contributor-handbook.md --- meta/contributor-handbook.md | 1 - 1 file changed, 1 deletion(-) diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index ffd3d0e23..b54ef36b4 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -83,6 +83,5 @@ Patterns of level 4 are stored in the directory `/4-established`. - Validation requirements: - Complies with *advanced style guide*(#) - *Oops! We have not yet developed this.* - - Community agreement (via lazy consensus of trusted committers) this representing universal truth about InnerSource (using best judgment) and it being responsible to push it out - Is free of conflicts with other InnerSource Commons learning materials and external InnerSource literature or adresses these conflicts explicitly From a61cd878fccbe4411d02a7c77b4120085a32e3b2 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Tue, 2 Jun 2020 12:41:24 +0200 Subject: [PATCH 24/27] Added top level patterns/ folder --- {1-initial => patterns/1-initial}/.gitkeep | 0 {2-structured => patterns/2-structured}/.gitkeep | 0 {3-validated => patterns/3-validated}/.gitkeep | 0 {4-established => patterns/4-established}/.gitkeep | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename {1-initial => patterns/1-initial}/.gitkeep (100%) rename {2-structured => patterns/2-structured}/.gitkeep (100%) rename {3-validated => patterns/3-validated}/.gitkeep (100%) rename {4-established => patterns/4-established}/.gitkeep (100%) diff --git a/1-initial/.gitkeep b/patterns/1-initial/.gitkeep similarity index 100% rename from 1-initial/.gitkeep rename to patterns/1-initial/.gitkeep diff --git a/2-structured/.gitkeep b/patterns/2-structured/.gitkeep similarity index 100% rename from 2-structured/.gitkeep rename to patterns/2-structured/.gitkeep diff --git a/3-validated/.gitkeep b/patterns/3-validated/.gitkeep similarity index 100% rename from 3-validated/.gitkeep rename to patterns/3-validated/.gitkeep diff --git a/4-established/.gitkeep b/patterns/4-established/.gitkeep similarity index 100% rename from 4-established/.gitkeep rename to patterns/4-established/.gitkeep From 6ba3bd1b367dd6384addc03f770342c31f9de60b Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Fri, 5 Jun 2020 13:43:23 +0200 Subject: [PATCH 25/27] Dropped double space --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d248383a5..a91046fcb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,7 +15,7 @@ Please consider contributing in the following ways: 3. **Review open pull requests.** Even without knowing all the specifics of the patterns working group, your feedback on existing [pull requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/labels/type%20-%20Content%20work) (especially those propising changes to pattern contents) will be valuable to its authors: As somebody who wants to learn more about InnerSource, you can give input from the perspective of a future reader. As somebody with own InnerSource experiences, you can share your experience with the authors. -4. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses all this in more detail. You don't feel ready yet to contribute a new pattern? Please start a discussion by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new). +4. **Contribute a new pattern.** A key contribution you can make is to document an InnerSource best practice you experienced or know about. We defined different maturity levels for the contents in this repository: First time contributors should aim for maturity levels `1: initial` (for unstructured experience reports or what we call donuts - patterns with missing pieces) and `2: structured` (for best practices adhering to the patterns format and following basic writing style conventions). Our [Contributor Handbook](meta/contributor-handbook.md) discusses all this in more detail. You don't feel ready yet to contribute a new pattern? Please start a discussion by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new). 5. **Be a patterns advocate.** The patterns will become better and cover more topics the more people contribute their perspective and experience. A colleague told you about a novel InnerSource best practice? Please invite her/him to contribute to this repository! From f8c121360b8edc45cf90955ca21e7a0bce57d539 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Fri, 5 Jun 2020 13:46:08 +0200 Subject: [PATCH 26/27] Dropped maturity level four --- meta/contributor-handbook.md | 26 +------------------------- patterns/4-established/.gitkeep | 0 2 files changed, 1 insertion(+), 25 deletions(-) delete mode 100644 patterns/4-established/.gitkeep diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index b54ef36b4..f998b5d2e 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -12,8 +12,7 @@ We defined four maturity levels for patterns: The higher a pattern's maturity le | ---- | ---- | ---- | ---- | | 1 | Initial | Contains an initial pattern idea or what we call a donut (a pattern with missing sections). | A few days / weeks | | 2 | Structured | Contains a complete pattern that it is not properly validated yet (e.g. because it only synthesizes an idea or the experiences from one instead of three organizations). | A few days / weeks | -| 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | One or two months | -| 4 | Established | The writing of the pattern is of "text book" quality. The community agrees to use this pattern as InnerSource teaching material. | As long as it takes | +| 3 | Validated | The pattern is validated (e.g. because three or more instances exists and are synthesized by the pattern) and its writing is of high quality. | A few months | For the first pattern you contribute, you should aim for maturity levels `1: initial` or `2: structured`. @@ -26,11 +25,6 @@ To achieve a given maturity level a pattern has to satisfy the requirements for Patterns (or other documents) of level 1 are stored in the directory `/1-initial`. -- Document types: - - Patterns (`pattern-*.md`) - - Donuts - patterns without solution or other missing sections (`donut-*.md`) - - Tale - unstructured information in any form (`tale-*.md`) - - Validation requirements: - N/A @@ -44,9 +38,6 @@ Patterns (or other documents) of level 1 are stored in the directory `/1-initial Patterns of level 2 are stored in the directory `/2-structured`. -- Document types: - - Patterns (`pattern-*.md`) - - Validation requirements: - Is validated by at least one known instance - Alternatively: key elements of the pattern have been validated in separate contexts and, in consequence, it is justified to believe the full solution will function @@ -60,9 +51,6 @@ Patterns of level 2 are stored in the directory `/2-structured`. Patterns of level 3 are stored in the directory `/3-validated`. -- Document types: - - Patterns (`pattern-*.md`) - - Validation requirements: - Is validated by at least three known instances - Considers all known instances to the best of working group members' knowledge @@ -72,16 +60,4 @@ Patterns of level 3 are stored in the directory `/3-validated`. - Uses & has no conflicts with working group terminology (defined by glossary / implicit usage) - *Oops! We have not yet developed this.* - Fits & has no conflicts with existing patterns (of this maturity level or higher) - Thorough review by at least two trusted committers - - -### Requirements: Level 4 - Established -Patterns of level 4 are stored in the directory `/4-established`. - -- Document types: - - Patterns (`pattern-*.md`) - -- Validation requirements: - - Complies with *advanced style guide*(#) - *Oops! We have not yet developed this.* - - Is free of conflicts with other InnerSource Commons learning materials and external InnerSource literature or adresses these conflicts explicitly - diff --git a/patterns/4-established/.gitkeep b/patterns/4-established/.gitkeep deleted file mode 100644 index e69de29bb..000000000 From a26932468039494cd7b04da06afe4e3d94cdac55 Mon Sep 17 00:00:00 2001 From: Maximilian Capraro Date: Mon, 8 Jun 2020 15:22:33 +0200 Subject: [PATCH 27/27] Update CONTRIBUTING.md Co-authored-by: Sebastian Spier --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a91046fcb..814d90629 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ For this working group to strive, we welcome your contribution - be it small or Please consider contributing in the following ways: -1. **Share your thoughts & spark discussion**. A fresh perspective, an intersting thought, or an early novel idea can spark discussions and yield unforeseeable results. We invite you to share your thoughts on InnerSource-related topics at any time by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new), [via Slack, or our patterns office hours](#how-to-get-in-touch). +1. **Share your thoughts & spark discussion**. A fresh perspective, an interesting thought, or an early novel idea can spark discussions and yield unforeseeable results. We invite you to share your thoughts on InnerSource-related topics at any time by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new), [via Slack, or our patterns office hours](#how-to-get-in-touch). 2. **Read & improve existing patterns.** If you want to get started, we encourage you to read through the existing patterns and materials in this repository. Found a misleading phrase or phony grammar? A mistake in the content? Let us know by [creating an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/new) or directly propose your fix as a pull request.