This document lays out a basic guideline of how to write and contribute a new pattern.
We have defined three maturity levels for patterns: The higher a pattern's maturity level, the more strictly it was validated and the better is its writing.
| # | 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. | A few months |
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 maturity level and lower levels. The following sections lay out the requirements per maturity level in detail.
Requirements: Level 1 - Initial
-
Validation requirements:
- N/A
-
Content requirements:
- The pattern is readable & comprehensible for others (not just for the authors)
- The authors contribute the contents according to the license & are allowed to do so
- Thoughts and contents by third parties are quoted / referenced explicitly
- The markdown of the pattern complies with Check: Markdownlint
-
Artifacts:
- The patterns are stored as markdown files in /patterns/1-initial.
Requirements: Level 2 - Structured
-
Validation requirements:
- Is validated by at least 1 (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
- Is validated by at least 1 (one) known instance
-
Content requirements:
- Uses the format described in the Pattern Template - validated in parts by Check: Pattern Syntax Validation
- Follows the Pattern Style Guide
- The title of the pattern is memorable, concise, and descriptive of what the pattern is about. For further tips see Naming Patterns.
- The pattern links to related patterns of this level or higher.
- Links from the pattern to outside resources are working and are referencing a trusted resource - whether links are working is verified by Check: Links
- The pattern is added to at least one phase of the InnerSource Program Mind Map.
- Spelling & Styles checks pass - see Check: Spelling & Styles
-
Artifacts:
- The patterns are stored as markdown files in /patterns/2-structured.
- The patterns are published at patterns.innersourcecommons.org - supported by automation via Book ToC Generation
Requirements: Level 3 - Validated
-
Validation requirements:
- Is validated by at least 3 (three) known instances
- Considers all known instances to the best knowledge of the working group
- Community agreement (via lazy consensus of trusted committers) on correctness of contents
-
Content requirements:
- Provides a visual/sketch that helps to illustrate the problem and/or the solution of the pattern. The visual also helps to make the pattern more memorable. Visuals are stored in assets/img.
- Uses & has no conflicts with working group terminology (defined by Glossary / implicit usage)
- Fits & has no conflicts with existing patterns (of this maturity level)
- Thorough review by at least two trusted committers
-
Artifacts:
- The patterns are stored as markdown files in /patterns/3-validated.
- The patterns are published at patterns.innersourcecommons.org - supported by automation via Book ToC Generation