You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You want to help us make this book better? That is awesome!
4
+
5
+
The InnerSource Patterns book itself is an open source project, and welcomes any form of contribution. Nothing is too small!
6
+
7
+
If you have never made a contribution to an open source project before, know that the InnerSource Patterns community is group of friendly people and with that a safe place to try it out :\)
8
+
9
+
## Before you get started
10
+
11
+
As the sources for the InnerSource Patterns and this book are kept in a repository on GitHub, you will need a user account there to make edits and suggestions to this book. If you don't have a user account at GitHub yet, head over to [github.com](https://github.com) and create one for free.
12
+
13
+
## Different ways to contribute
14
+
15
+
Here a few ways in which you can contribute:
16
+
17
+
1. fix spelling, formatting, or other glitches that you notice in this book
18
+
2. improve the content of an existing pattern \(e.g. by adding a short description of how you are using a pattern as a _Known Instance_\)
19
+
3. contribute a new pattern, describing how you have overcome InnerSource-related challenges in your organization
20
+
21
+
For \(1\) and \(2\) above you can simply hit the **Edit on GitHub** link that you see at the top of each page in the book. This will take you straight to the respective file in our GitHub repository, where you can suggest your changes.
22
+
23
+
For \(3\) you need to clone the [InnerSourcePatterns](https://github.com/InnerSourceCommons/InnerSourcePatterns) repository, and add a new file with your suggested pattern. When making such larger contributions to this book please review our [CONTRIBUTING.md](https://github.com/spier/InnerSourcePatterns/tree/72f5dd292e2e9d10384693ecad2498052d275574/CONTRIBUTING.md) and also our [Contributor Handbook](https://github.com/spier/InnerSourcePatterns/tree/72f5dd292e2e9d10384693ecad2498052d275574/meta/contributor-handbook.md).
24
+
25
+
## License of Contributions
26
+
27
+
The contents of this repository are licensed under [CC-BY-SA-4.0](https://github.com/spier/InnerSourcePatterns/tree/72f5dd292e2e9d10384693ecad2498052d275574/LICENSE.txt). 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.
Provide information on what kinds of contributions your project is looking for here. For example these can be bug reports, help with answering user questions, improving documentation, fixes to bugs, as well as new feature implementations.
6
+
7
+
## Bug reports
8
+
9
+
Add information on how to submit bug reports here. This should include hints about which type of information the project will need in order to reproduce and fix issues. It can also include information on commonly found mis-configurations that look like bugs.
10
+
11
+
Also include information on what contributors can expect in terms of time to first response and process after that.
12
+
13
+
## Feature requests
14
+
15
+
Add information on how to submit feature requests here. Also include information on what contributors can expect in terms of time to first response and process after that.
16
+
17
+
## Contributing documentation
18
+
19
+
Include information on any documentation best practices your project follows as well as how to build documentation, checks to run and how to submit the changes made back to the project.
20
+
21
+
## Contributing source code
22
+
23
+
This section should contain information on
24
+
25
+
* How to access the project source code,
26
+
* General project layout,
27
+
* Any requirements to the development environment,
28
+
* Code formatting guidelines,
29
+
* How to run the test suite.
30
+
31
+
## How to become a Trusted Committer
32
+
33
+
This section should make the process for becoming a Trusted Committer explicit if that route is open to contributors.
34
+
35
+
## How to nominate Trusted Committers
36
+
37
+
This section serves as a reminder to existing and explanation for new Trusted Committers detailing how to add others to the host team. Again ideally this information is identical for all projects in the organisation so central information can be linked to from here.
This should contain a brief \(3-5 sentences\) description of the mission of your project. The goal is to state what you are planning to work on and help external contributors understand roughly which types of features will likely be welcome for this project.
6
+
7
+
See also [mission statement chapter](https://producingoss.com/en/producingoss.html#mission-statement) in Producing Open Source Software.
8
+
9
+
## Getting Started
10
+
11
+
This section should contain brief documentation written for first time users on how to get started using the project. Further more detailed documentation can be linked to from here.
12
+
13
+
## Further information
14
+
15
+
This section can list any or all of the following:
16
+
17
+
* A list of features, use cases that the software addresses.
18
+
* Information on design principles that are used to resolve trade-offs
19
+
* Links to further user level documentation
20
+
* Answers to frequently asked questions \(FAQ\), preferably in a format that
21
+
22
+
allows to link to specific questions and their answers for easier reference.
23
+
24
+
## Getting help
25
+
26
+
This section should contain a brief documentation on how to get help for the project as a user. This could be as simple as pointing users to the issue tracker if this is how your project would like to answer questions. It could also point to an archived and searchable chat channel, some archived searchable mailing list, some online user forum.
27
+
28
+
## Getting involved
29
+
30
+
This section should include information on how to get in touch with the project: Typically this will contain links to archived, searchable and linkable communication channels.
31
+
32
+
## Who we are
33
+
34
+
This is a good place to give credit to Trusted Committers of the project.
35
+
36
+
It's also a good place to include information on what being a Trusted Committer means for this project - although ideally all projects in an organisation use the same definition that is only linked to from here. The reason to keep the link here is for colleagues who have no or little experience with working in and contributing to InnerSource projects to have a direct link back to company wide information from the technological projects they need for their daily work.
37
+
38
+
## Contributing
39
+
40
+
This section should document \(or link to documentation\) on all things that a first time contributor needs to know to get started. Typically not all of the topics below will be covered. Focus on what differs in your project from standard setup and what previous contributors found hard to understand.
41
+
42
+
* Finding the source code.
43
+
* Finding a list of issues that your project needs help with - these can be
44
+
45
+
both, technical and non-technical issues. Typically you will keep those in an
46
+
47
+
issue tracker accessible to contributors.
48
+
49
+
* Links to further documentation e.g. about the architecture of the project,
50
+
51
+
general coding conventions, testing conventions...
52
+
53
+
* For technical contributions: Making changes, building the project and testing
54
+
55
+
your changes.
56
+
57
+
* Submitting your changes back to the project.
58
+
59
+
Ideally you also include information on what the preferred process for changes looks like for the project: Should contributors first open an issue and submit a proposal, or are they welcome to submit changes right away? What is important to you when reviewing contributions?
60
+
61
+
In addition you should outline any design values you want to follow in the project. Making those explicit often helps resolve trade-offs more quickly and more easily. In addition it helps making changes to otherwise implicit assumptions transparent.
62
+
63
+
Over time you will notice that this section grows substantially. In that case think about moving the information to separate files, e.g. a CONTRIBUTING.md and TESTING.md
Concise 1-2 sentence description of the problem and solution. Readers may quickly review dozens of these patlets to discover and browse the larger library of patterns. From [http://wiki.c2.com/?PatLet](http://wiki.c2.com/?PatLet)
10
+
11
+
## Problem
12
+
13
+
What is the problem - crisp definition of the problem. Short description, usually not more than a couple sentences, that describes what the issues and challenges are. Be careful not to morph into information found in other sections below.
14
+
15
+
## Story \(optional\)
16
+
17
+
Sometimes there is a story that helps people understand the pattern better.
18
+
19
+
## Context
20
+
21
+
Where does the problem exist? What are the pre-conditions? **Unchangeable** before the solution goes into place. The content here is often tied to the applicability of the pattern for other readers: "Do I have this same particular situation?"
22
+
23
+
## Forces
24
+
25
+
What makes the problem difficult? What are the trade-offs? These are constraints that **can be changed** at a cost. The solution might change one or more of these forces in order to solve the problem, while also in-turn changing the context.
26
+
27
+
## Sketch \(optional\)
28
+
29
+
visual illustration
30
+
31
+
## Solutions
32
+
33
+
Verified resolutions and possible resolutions to the problem.
34
+
35
+
## Resulting Context
36
+
37
+
What is the situation after the problem has been solved? The original context is changed indirectly by way of the solution. Often this section can include discussion of the next possible Patterns/problems introduced. This section can be short in content - the solution may not introduce new problems or change much context.
38
+
39
+
## Rationale \(optional\)
40
+
41
+
Explains why this is the right solution; using totally different words WHY this solution balances these forces and this context to solve this problem. Can expand on what-if's or theories.
42
+
43
+
## Known Instances \(optional\)
44
+
45
+
Where has this been seen before? Helps to reinforce that this is a REAL pattern and that you match the context.
46
+
47
+
May mention:
48
+
49
+
* A particular business
50
+
* Anonymized instances ex: "3 companies have proven that this is a good solution" or "A large financial services org...".
51
+
52
+
## Status \(optional until merging\)
53
+
54
+
General pattern status is stored in GitHub's Label tagging - see any pull request. Note that this GitHub label tagging becomes less visible once the pattern is finalized and merged, so having some information in this field is helpful.
55
+
56
+
You might store other related info here, such as review history: "Three of us reviewed this on 2/5/17 and it needs John's expertise before it can go further."
57
+
58
+
## Author\(s\)\(optional\)
59
+
60
+
Often, this is yourself; If you need to, find someone in the InnerSource Commons to be the nominal author \(As Told To\); Could also be no-one if you do not want to take on authorship \(common with a donut looking for a solution\)
61
+
62
+
## Acknowledgements \(optional\)
63
+
64
+
Include those who assisted in helping with this pattern - both for attribution and for possible future follow up. Though optional, most patterns should list who helped in their creation.
65
+
66
+
## Alias \(optional\)
67
+
68
+
If this pattern is also known under a different name than what is listed unter **Title**, please list those alternative titles here. e.g. if the pattern is named after the problem it solves, a helpful alias might be one that describes the solution that is applied.
This is an early release of the InnerSource Patterns book.
7
-
You may still find broken links, spelling mistakes, or other errors in this book.
8
-
Please help us to fix them to produce the best book possible :). Learn how to [contribute to this book](../book/contribute-to-this-book.md).
6
+
This is an early release of the InnerSource Patterns book. You may still find broken links, spelling mistakes, or other errors in this book. Please help us to fix them to produce the best book possible :\). Learn how to [contribute to this book](../appendix/contribute-to-this-book.md).
9
7
{% endhint %}
10
8
11
9
Welcome to the **InnerSource Patterns book**.
@@ -14,9 +12,9 @@ This book contains InnerSource best practices codified in a specific format to m
14
12
15
13
These patterns have been collected by the [InnerSource Commons](http://innersourcecommons.org) community over many years. The most mature patterns have been published in this book. Mature in this context means that each pattern has been reviewed by members of the community, and has at least one known instance where this pattern has been used.
16
14
17
-
In this introduction we explain [what InnerSource is](#what-is-innersource), [what a pattern is](#what-are-innersource-patterns), and [how to use these patterns](#how-can-you-use-innersource-patterns) in your organization.
15
+
In this introduction we explain [what InnerSource is](introduction.md#what-is-innersource), [what a pattern is](introduction.md#what-are-innersource-patterns), and [how to use these patterns](introduction.md#how-can-you-use-innersource-patterns) in your organization.
18
16
19
-
If you are using InnerSource in your company already and want to contribute your experiences to this book we would love to [welcome your contributions](../book/contribute-to-this-book.md)!
17
+
If you are using InnerSource in your company already and want to contribute your experiences to this book we would love to [welcome your contributions](../appendix/contribute-to-this-book.md)!
20
18
21
19
## What is InnerSource?
22
20
@@ -35,19 +33,19 @@ Patterns are a way of describing a repeatable, proven solution to a problem with
35
33
In inner sourcing, patterns can provide a way for the InnerSource Commons participants to concisely share information with each other, improving the practice of inner sourcing. Each of the patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections.
36
34
37
35
*[`What are patterns?` Youtube videos](http://bit.ly/innersource_patterns_videos) - Watch a set of 2-5 min youtube videos explaining InnerSource Patterns
38
-
*[Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU) - We held a webinar 2017-03-16 to live-discuss a donut pattern (go to 24:30 for the discussion). This is an illustration of the review process we follow. Also see the [June 1, 2017 O'Reilly Webinar on InnerSource Patterns](http://www.oreilly.com/pub/e/3884).
39
-
*[Pattern Template](../meta/pattern-template.md) - View a skeleton inner source pattern to get an idea on what goes into a new pattern!
40
-
*[Introduction to InnerSource Patterns (2016 Fall Summit presentation)](https://drive.google.com/open?id=0B7_9iQb93uBQbnlkdHNuUGhpTXc) - *Tim Yao and Padma Sudarsan*(PDF). Detailed pattern background and examples -- Get a detailed understanding of why and how to interact with our patterns. Also see the [Introduction to InnerSource Patterns (2017 Fall Summit)](https://drive.google.com/open?id=0B7_9iQb93uBQWmYwMFpyaGh4OFU)*Tim Yao and Bob Hanmer*(PDF).
36
+
*[Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU) - We held a webinar 2017-03-16 to live-discuss a donut pattern \(go to 24:30 for the discussion\). This is an illustration of the review process we follow. Also see the [June 1, 2017 O'Reilly Webinar on InnerSource Patterns](http://www.oreilly.com/pub/e/3884).
37
+
*[Pattern Template](../appendix/pattern-template.md) - View a skeleton inner source pattern to get an idea on what goes into a new pattern!
38
+
*[Introduction to InnerSource Patterns \(2016 Fall Summit presentation\)](https://drive.google.com/open?id=0B7_9iQb93uBQbnlkdHNuUGhpTXc) - _Tim Yao and Padma Sudarsan_\(PDF\). Detailed pattern background and examples -- Get a detailed understanding of why and how to interact with our patterns. Also see the [Introduction to InnerSource Patterns \(2017 Fall Summit\)](https://drive.google.com/open?id=0B7_9iQb93uBQWmYwMFpyaGh4OFU)_Tim Yao and Bob Hanmer_\(PDF\).
41
39
42
40
## How can you use InnerSource Patterns?
43
41
44
-
Patterns must be used in a thoughtful manner. They cannot be blindly applied. In most cases, you will need to adapt the given solution to your own situation; but the information given in the pattern, defining the context (immovable constraints) and forces (constraints that can be changed and balanced against each other), should help you do this. Note that you will also need to determine if there are additional constraints (company context and company forces) that apply to your particular company/organization that must be added to the pattern (as a kind of filter). These additional constraints may require additional solution steps to be applied.
42
+
Patterns must be used in a thoughtful manner. They cannot be blindly applied. In most cases, you will need to adapt the given solution to your own situation; but the information given in the pattern, defining the context \(immovable constraints\) and forces \(constraints that can be changed and balanced against each other\), should help you do this. Note that you will also need to determine if there are additional constraints \(company context and company forces\) that apply to your particular company/organization that must be added to the pattern \(as a kind of filter\). These additional constraints may require additional solution steps to be applied.
45
43
46
-
The pattern form is useful for describing proven solutions but it can also be used for *brainstorming new solutions* where patterns are not yet established. This is, because the anatomy of a pattern provides a frame for thinking about a problem in a structured manner. You could also create a *donut pattern*(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).
44
+
The pattern form is useful for describing proven solutions but it can also be used for _brainstorming new solutions_ where patterns are not yet established. This is, because the anatomy of a pattern provides a frame for thinking about a problem in a structured manner. You could also create a _donut pattern_\(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\).
47
45
48
46
## How to Contribute?
49
47
50
-
Please refer to: [Contribute to this book](./contribute-to-this-book.md)
48
+
Please refer to: [Contribute to this book](../appendix/contribute-to-this-book.md)
51
49
52
50
## Credits
53
51
@@ -57,10 +55,11 @@ We want to specifically mention the InnerSource Patterns Working Group. They hav
57
55
58
56
The title image of this book was created by [Sebastian Spier](https://spier.hu) and adapted from an image by [Tony Hisgett - Alhambra 6](https://www.flickr.com/photos/hisgett/29345405788/), available under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).
59
57
60
-
**Thank you to all contributors! And happy InnerSource Day :)**
58
+
**Thank you to all contributors! And happy InnerSource Day :\)**
InnerSourcePatterns by [InnerSourceCommons.org](http://innersourcecommons.org) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International](http://creativecommons.org/licenses/by-sa/4.0/) License.
0 commit comments