diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e529a245..814d90629 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,95 +1,39 @@ -# 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](meta/pattern-template.md). More infos on the working group can be found in our [README.md](README.md) 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. **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. -# A. Writing a New Pattern +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. -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. **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). -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) +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! -Creating a new pattern -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) +## How to get in touch? -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). +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. -## Use Branches When Creating New Patterns -We develop new patterns in branches with the naming convention: -`pattern/`. +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/). -If you are asked to 'Commit directly...' vs 'Create a new branch...' -* 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. +## License of Contributions +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 -* 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. +## Code of Conduct -# 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. diff --git a/README.md b/README.md index 2f2f64f4a..0c3f0d0f6 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](CONTRIBUTING.md) for details on getting involved. To learn how we define, operate, and upkeep this collection of patterns, take a look at [Pattern Meta Info](./meta). - -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. ## Related References diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md new file mode 100644 index 000000000..f998b5d2e --- /dev/null +++ b/meta/contributor-handbook.md @@ -0,0 +1,63 @@ +# 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. + +### In a Nutshell + +| \# | 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 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`. + +- 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.txt) & 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`. + +- 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 + +- Content requirements: + - Complies with the [patterns format](pattern-template.md) + - Complies with *basic style guide*(#) - *Oops! We have not yet developed this* + + +### Requirements: Level 3 - Validated + +Patterns of level 3 are stored in the directory `/3-validated`. + +- Validation requirements: + - Is validated by at least three known instances + - Considers all known instances to the best of working group members' knowledge + - 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 + 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. 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 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 diff --git a/patterns/1-initial/.gitkeep b/patterns/1-initial/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/patterns/2-structured/.gitkeep b/patterns/2-structured/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/patterns/3-validated/.gitkeep b/patterns/3-validated/.gitkeep new file mode 100644 index 000000000..e69de29bb