+
This repository contains the InnerSource Patterns collected by the [InnerSource Commons][isc-website]. These patterns are InnerSource best practices codified in a specific format to make it easy to understand, evaluate, and reuse them.
@@ -9,20 +13,20 @@ If you are here for the first time, you may start by reading our most mature pat
Below you find [what a pattern is](#what-are-innersource-patterns), a [list of known patterns](#list-of-patterns), and [how to use these patterns](#how-can-you-use-innersource-patterns) in your organization.
-You are already using InnerSource in your company and want to share your ideas and experiences with the world? We would love to [welcome your contributions](#how-to-contribute)!
+Are you already using InnerSource in your company? If you would like to share your experiences with the world, we would love to [welcome your contributions](#how-to-contribute)!
[isc-website]: http://innersourcecommons.org
## Mission Statement
-Our mission in this working group
+Our mission
-- Collect and document agreed upon best practices of how to do InnerSource - in the form of patterns
-- Continuously publish the most mature patterns as an ebook
+- Collect and document best practices on how to do InnerSource - in the form of patterns
+- Publish the most mature patterns as an ebook
## List of Patterns
-The below lists all known patterns. They are grouped into three [maturity levels](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/meta/contributor-handbook.md#maturity-levels).
+ All known patterns (grouped into three [maturity levels](./meta/contributor-handbook.md#maturity-levels)) are as follows:
### Maturity Level 3: Validated
@@ -37,7 +41,7 @@ The below lists all known patterns. They are grouped into three [maturity levels
* [Gig Marketplace](patterns/2-structured/gig-marketplace.md) - *Establish a marketplace by creating an intranet website that lists specific InnerSource project needs as "Gigs" with explicit time and skill requirements. This will enable managers to better understand their employee’s time commitment and professional benefits thereby increasing the likelihood of garnering approval to make InnerSource contributions.*
* [Maturity Model](patterns/2-structured/maturity-model.md) - *Teams have started adopting InnerSource. The practice is spreading to multiple departments. Understanding of what constitutes an InnerSource project are wide spread though. The solution is to provide a maturity model to allow for teams to go through a self check and discover patterns and practices that they are not yet aware of.*
* [InnerSource License](patterns/2-structured/innersource-license.md) - *Two legal entities that belong to the same organization want to share software source code with each other but they are concerned about the implications in terms of legal liabilities or cross-company accounting. An InnerSource License provides a reusable legal framework for the sharing of source code within the organization. This opens up new collaboration options, and makes the rights and obligations of the involved legal entities explicit.*
-* [InnerSource Portal](patterns/2-structured/innersource-portal.md) - *Create an intranet website that indexes all available InnerSource project information. This will enable potential contributors to more easily learn about projects that might interest them and for InnerSource project owners to attract an outside audience.*
+* [InnerSource Portal](patterns/2-structured/innersource-portal.md) - *Potential contributors cannot easily discover InnerSource projects that they are interested in. By creating an intranet website that indexes all available InnerSource project information you enable contributors to learn about projects that might interest them and InnerSource project owners to attract an outside audience.*
* [Praise Participants](patterns/2-structured/praise-participants.md) - *Thank contributors effectively to engender further engagement from them and to encourage others to contribute*
* [Repository Activity Score](patterns/2-structured/repository-activity-score.md) - *The repository activity score is a numeric value that represents the (GitHub) activity of an InnerSource project.*
* [Review Committee](patterns/2-structured/review-committee.md) - *The InnerSource working model is a radical departure from more traditional approaches, for developers and managers alike. By establishing a review committee as an interface between the InnerSource initiative and all senior managers of business units participating in it, the latter are more likely to familiarise themselves with the initiative and support it, as it affords them a certain level of oversight and control without fostering micromanagement.*
@@ -51,10 +55,11 @@ The below lists all known patterns. They are grouped into three [maturity levels
* [Start as an Experiment](patterns/2-structured/start-as-experiment.md) - *Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative.*
* [Core Team](patterns/2-structured/core-team.md) - *Even when an InnerSource project is widely needed, contributions and usage may be hindered because the project is difficult to work with. Establish a core team that is dedicated to take care of the project's fundamental items. Their work enables contributors to add and use the features that provide value to their scenarios.*
* [Document your Guiding Principles](patterns/2-structured/document-your-guiding-principles.md) - *The usual InnerSource explanation of "applying open source best practices inside an organisation" does not work well with people lacking an open source background. As a remedy the most important principles of InnerSource get documented and published widely.*
+* [Extensions for Sustainable Growth](/patterns/2-initial/extensions-for-sustainable-growth.md) - *An InnerSource project is receiving too many contributions, making maintenance difficult. By offering an extension mechanism outside of the core project, the maintainers enable scaling of project capabilities with minimal cost and maintenance overhead.*
### Maturity Level 1: Initial
-* [Modular Code](patterns/1-initial/modular-code.md) - *Management does not want to spend the extra resources needed to develop modular components and make them available in a visible repository for others to use.*
+* [Modular Code](patterns/1-initial/modular-code.md) - *The lack of modularization in the software architecture prevents reuseability, and with that the ability to reap the benefits of InnerSource. By helping the teams to understand the benefits of modularization, and making time to work towards that goal, more InnerSource collaboration can happen and the software architecture overall can be improved.*
* [Improve Findability](patterns/1-initial/improve-findability.md) - *People can't find the internally developed solutions that they need due to poor naming conventions. This causes frustration in finding InnerSource solutions and a reduction in code reuse.*
* [Overcoming Project Management Time Pressures](patterns/1-initial/overcoming-project-management-time-pressures.md) - *Project management believes timeline pressure and commitments on feature content does not allow for developers to spend the time needed to develop shareable code and provide support.*
* [Introducing Metrics in InnerSource](patterns/1-initial/introducing-metrics-in-innersource.md) - *Involve all stakeholders in designing and interpreting metrics to measure the current status in terms of health and performance of the InnerSource initiative.*
@@ -71,10 +76,15 @@ The below lists all known patterns. They are grouped into three [maturity levels
* [Unified Source Code Inventory](patterns/1-initial/source-code-inventory.md) - *In a large organization with different legal entities is often hard to get full visibility into all software assets, in particular all source code. This situation reduces the opportunities to increase business value and keep liability costs, such as software maintenance, under control across the organization as a whole. An organization-level source code inventory addresses these issues while exploiting opportunities to identify and support valuable InnerSource assets.*
* [Explicit Shared Ownership](patterns/1-initial/explicit-shared-ownership.md) - *A software component that several teams depend on has grown to the point where owners are no longer capable of taking full ownership. There is confusion who to involve for changes. Sharing ownership explicitly and making expected behaviour visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership.*
* [Standarized Release Process](patterns/1-initial/release-process.md) - *Teams may be reluctant to use InnerSource projects that they are unfamiliar with when there is no clear release process apparent in the repository. Providing clear release notes and a published artifact (binary, docker image, jar, etc) gives people confidence you are publishing a quality product.*
-* [Overcoming the Not-Invented-Here Mindset](/patterns/1-initial/not-invented-here.md) - Perfectly good solutions are being rejected because of "Not Invented Here" (NIH). Engineers and their managers will choose to implement functionality themselves first, even if an alternative exists. A shift towards a culture of "Proudly Found Elsewhere" can help reduce the negative impact of NIH.
+* [Overcoming the Not-Invented-Here Mindset](/patterns/1-initial/not-invented-here.md) - *Perfectly good solutions are being rejected because of "Not Invented Here" (NIH). Engineers and their managers will choose to implement functionality themselves first, even if an alternative exists. A shift towards a culture of "Proudly Found Elsewhere" can help reduce the negative impact of NIH.*
+* [Balancing Openness and Security](/patterns/1-initial/balancing-openness-and-security.md) - *While InnerSource flourishes in environments with a high degree of shared code, Security/Legal prefers the limitation of source code access to only those that need it. By making Security/Legal part of the team, introducing explicit sharing levels and security policies for shared repositories, as well as defining what qualifies as sensitive information, code sharing can be facilitated while minimizing the associated risks.*
+* [Crossing the InnerSource Chasm](/patterns/1-initial/crossing-chasm.md) - *Early InnerSource experiments have been successful. Methods that were successful convincing early teams stop working though when scaling the initiative. This chasm can be crossed by using different methods to reach people at different stages of the innovation curve.*
+* [Transitioning Contractor Code to InnerSource Model](/patterns/1-initial/transitioning-contractor-code-to-innersource-model.md) - *Contract developers are often not motivated to engage in InnerSource activities, which may be beyond the scope of their contract. This pattern describes how you can focus on transitioning the contractor project after the fact to an InnerSource project by setting expectations for specific InnerSource-related deliverables as part of the overall project delivery.*
+* [Incubator Pipeline](/patterns/1-initial/incubator-pipeline.md) - *A team maintaining a widely shared code library wants to accept contributions from other teams, without lowering the overall quality of their library. Therefore the shared library team uses an incubator pipeline to set a lower bar for contributions to enter and a higher bar to exit and become a top-level unit in the library.*
+* [InnerSource Customer Interview Questions](/patterns/1-initial/innersource-customer-interview-questions.md) - *An organization has decided to create an InnerSource program but are unsure which issues they should address first. Using a customer interview will help evaluate pain points across the organization, to prioritize the areas where InnerSource will have the biggest positive impact.*
@@ -93,7 +103,6 @@ This is why we keep these patterns at the bottom of the list.
#### Donuts (needing a solution)
* [How to Defeat the Hierarchical Constraints](patterns/1-initial/defeat-hierarchical-constraints.md)
-* [Project Management Time Pressures](patterns/1-initial/overcoming-project-management-time-pressures.md)
* [Organizational Mindset Change](patterns/1-initial/organizational-mindset-change.md)
* [Bad Weather For Liftoff](patterns/1-initial/bad-weather-for-liftoff.md)
* [Incentive mechanisms to foster voluntary contribution](patterns/1-initial/incentive-mechanisms-for-voluntary-contribution.md)
@@ -106,16 +115,16 @@ Patterns are a way of describing a repeatable, proven solution to a problem with
Patterns can provide a way for the InnerSource Commons participants to concisely share information, improving the practice of InnerSource. Patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections.
* [What are patterns?](https://bit.ly/innersource_patterns_videos) - Watch a set of 2-5 min videos explaining InnerSource Patterns
-* [Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU?t=1479) - We held a webinar 2017-03-16 to live-discuss a donut pattern (go to [24:40](https://youtu.be/i-0IVhfRVFU?t=1479) 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).
+* [Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU?t=1479) - We held a webinar 2017-03-16 to have a live discussion on a donut pattern (go to [24:40](https://youtu.be/i-0IVhfRVFU?t=1479) 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).
* [Pattern Template File](meta/pattern-template.md) - View a skeleton InnerSource pattern to get an idea on what goes into a new pattern!
* [Introduction to InnerSource Patterns (2016 Fall Summit)](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).
* A scientific look at how to write patterns: [A pattern language for pattern writing](http://hillside.net/index.php/a-pattern-language-for-pattern-writing), Meszaros and Doble
## How can you use InnerSource Patterns?
-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.
+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. However, the information found in the pattern, and defining the context (immovable constraints) and forces (constraints that can be changed and balanced against each other), will help you adapt. In addition, you need to determine if there are further constraints (company context and company forces) that apply to your company/organization that must be added to the pattern. These additional constraints may require additional solution steps to be applied.
-The pattern form is useful for describing proven patterns but it can also be used for *brainstorming solutions* where patterns are not yet established, since the form gives a structured way for thinking about a problem. 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).
+The pattern form is useful for describing proven patterns but it can also be used for *brainstorming solutions* where patterns have not yet been established, since the form provides a structured way of thinking about a problem. 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).
## How to Contribute?
diff --git a/TRUSTED-COMMITTERS.md b/TRUSTED-COMMITTERS.md
index fab7c6e6f..7dcd8eb4a 100644
--- a/TRUSTED-COMMITTERS.md
+++ b/TRUSTED-COMMITTERS.md
@@ -10,6 +10,8 @@ For further information about the concept, also see the [Trusted Committer Patte
## Current Trusted Committers
+* [@yuhattor](https://github.com/yuhattor) (added 2022-07-21)
+* [@robtuley](https://github.com/robtuley) (added 2022-02-15)
* [@spier](https://github.com/spier) (added 2020-12-11)
* [@lenucksi](https://github.com/lenucksi) (added 2020-04-24)
* [@NewMexicoKid](https://github.com/NewMexicoKid) (added 2017-03-02)
@@ -30,25 +32,29 @@ The alumni in the Hall of Fame can of course always start contributing again in
We work based on trust: Our goal is to add most people who contributed a sizeable change - quick and early.
-We follow this process (adapted from [here](https://tech.europace.de/voting-in-new-trusted-committers/)):
+We follow this process:
-1. Any trusted committer (TC) can step forward and nominate a new TC in the private Slack channel #innersource-patterns-tcs. The TC should provide the following information:
+1. Any trusted committer (TC) can nominate a new TC in the private Slack channel `#innersource-patterns-tcs`. The TC should provide the following information:
* Name of the candidate
* Reason for candidate
* Github handle of the candidate
* Slack handle of the candidate
-1. Every TC can raise concerns or second the nomination in the #innersource-patterns-tcs channel.
-1. If none of the existing TCs disagrees with the nomination within 72h, [lazy consensus](https://tech.europace.de/lazy-consensus-vs-explicit-voting/) is reached: The nomination is accepted.
-1. The TC who nominated the candidate informs her/him in private about the nomination and its acceptance. The candidate can decide on whether to accept or reject the offer.
-1. If the candidate accepts the offer, the TC who nominated the candidate, makes sure:
- * New TC is added to this file (`TRUSTED-COMMITTERS.md`)
- * New TC is added to `.github/CODEOWNERS`, so that they get notified about new PRs automatically
- * New TC receives write access to this repository
- * New TC is added to the #innersource-patterns-tcs channel
- * New TC is praised in the [#innersource-patterns](https://app.slack.com/client/T04PXKRM0/C2EFRTS6A) channel.
+2. Every TC can raise concerns or second the nomination in the #innersource-patterns-tcs channel.
+3. If none of the existing TCs disagrees with the nomination within 72h, [lazy consensus](https://tech.europace.de/lazy-consensus-vs-explicit-voting/) is reached: The nomination is accepted.
+4. The TC who nominated the candidate informs her/him in private about the nomination and its acceptance. The candidate can decide on whether to accept or reject the offer.
+5. If the candidate accepts the offer, the TC who nominated the candidate, makes sure:
+ 1. New TC receives write access to this repository (this needs to happen first, so that step 5.iii works)
+ 2. New TC is added to this file (`TRUSTED-COMMITTERS.md`)
+ 3. New TC is added to `.github/CODEOWNERS`, so that they get notified about new PRs automatically
+ 4. New TC is added to the `#innersource-patterns-tcs` channel
+ 5. New TC is praised in the [#innersource-patterns](https://app.slack.com/client/T04PXKRM0/C2EFRTS6A) channel.
## Admins
A handful of individuals are currently the technical GitHub Admins for this repository. This includes most members of the InnerSource Commons' #tech-infra team and members of the [InnerSource Commons GitHub Organization](https://github.com/innersourcecommons).
However, please channel working group-specific requests through the trusted committers.
+
+## References
+
+Our trusted committer process was inspired by [this](https://tech.europace.de/voting-in-new-trusted-committers/).
diff --git a/assets/img/extensions-for-sustainable-growth/README.md b/assets/img/extensions-for-sustainable-growth/README.md
new file mode 100644
index 000000000..8db50a0c6
--- /dev/null
+++ b/assets/img/extensions-for-sustainable-growth/README.md
@@ -0,0 +1 @@
+If you want to edit the illustration, please request access to this [source document](https://docs.google.com/presentation/d/1uyvRcIIrxKedajB6XeGL21_2p60oGOi-nrU6pwk5YqA/edit#slide=id.g1af54b5764d_0_135).
diff --git a/assets/img/extensions-for-sustainable-growth/extensions-for-sustainable-growth.png b/assets/img/extensions-for-sustainable-growth/extensions-for-sustainable-growth.png
new file mode 100644
index 000000000..2e347f984
Binary files /dev/null and b/assets/img/extensions-for-sustainable-growth/extensions-for-sustainable-growth.png differ
diff --git a/assets/img/flutter-pyramid.svg b/assets/img/flutter-pyramid.svg
new file mode 100644
index 000000000..a23d324d4
--- /dev/null
+++ b/assets/img/flutter-pyramid.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/assets/img/mercadolibre-trusted-committers.png b/assets/img/mercadolibre-trusted-committers.png
new file mode 100644
index 000000000..aa17a2afe
Binary files /dev/null and b/assets/img/mercadolibre-trusted-committers.png differ
diff --git a/assets/img/portal-overview.png b/assets/img/portal-overview.png
new file mode 100644
index 000000000..8269187d1
Binary files /dev/null and b/assets/img/portal-overview.png differ
diff --git a/assets/img/rfc-process-uber-baseui.png b/assets/img/rfc-process-uber-baseui.png
new file mode 100644
index 000000000..6039637ec
Binary files /dev/null and b/assets/img/rfc-process-uber-baseui.png differ
diff --git a/assets/img/santander_portal.png b/assets/img/santander_portal.png
new file mode 100644
index 000000000..b5ad2e80a
Binary files /dev/null and b/assets/img/santander_portal.png differ
diff --git a/assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png b/assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png
new file mode 100644
index 000000000..0d773f30d
Binary files /dev/null and b/assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png differ
diff --git a/assets/img/standard-base-documentation/README-for-users.png b/assets/img/standard-base-documentation/README-for-users.png
new file mode 100644
index 000000000..0436e79aa
Binary files /dev/null and b/assets/img/standard-base-documentation/README-for-users.png differ
diff --git a/assets/img/standard-base-documentation/README.md b/assets/img/standard-base-documentation/README.md
new file mode 100644
index 000000000..22160c45a
--- /dev/null
+++ b/assets/img/standard-base-documentation/README.md
@@ -0,0 +1,11 @@
+# Credits
+
+The current illustration is a digital remake of this [original visual](/patterns/2-structured/project-setup/assets/base_docs_drawing.png).
+If you want to edit this illustration, please request access to this [source document](https://docs.google.com/presentation/d/11JOByEO9QXlRLXX5BIv9rjUzPzCKErZzknD1OLcprQQ/edit?usp=sharing).
+
+The humans in the illustration are [bro](https://storyset.com/illustration/coding/bro) and [pana](https://storyset.com/illustration/high-five/pana) from Storyset.
+
+See:
+
+- [Web illustrations by Storyset](https://storyset.com/web)
+- [People illustrations by Storyset](https://storyset.com/people)
diff --git a/book/README.md b/book/README.md
index 86bb76010..ce3ccff0d 100644
--- a/book/README.md
+++ b/book/README.md
@@ -1,28 +1,51 @@
# How to generate the InnerSource Patterns gitbook
-Whenever changes to the [InnerSource Patterns][InnerSourcePatterns] GitHub repository are made, a new version of our InnerSource Patterns book is published at [patterns.innersourcecommons.org][book_production].
+Whenever changes to the [InnerSource Patterns GitHub repository][InnerSourcePatterns] are made, a new version of the InnerSource Patterns book is published at [patterns.innersourcecommons.org][book_production].
## Where is the book published?
-The most up-to-date version of the book is available for readers/consumers at [patterns.innersourcecommons.org][book_production].
+The latest version of the book is available for readers at [patterns.innersourcecommons.org][book_production].
-We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes. If you want to make any structural changes to the book, please send a PR to merge your changes into the `book-staging` branch. That way we can test your changes on the Staging version first, before they go live.
+We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes. If you want to make structural changes to the book, please contact us via a GitHub issue first.
## Which patterns are published?
-The book contains patterns of maturity **Structured** (Level 2) or **Validated** (Level 3). **Initial** (Level 1) patterns are not published in the book, because those are still subject to a lot of change, and have likely not even proven to work yet. For more on these maturity levels see the [Contributor Handbook](../meta/contributor-handbook.md).
+The book contains patterns of maturity **Structured** (Level 2) or **Validated** (Level 3).
-## How does it work?
+**Initial** (Level 1) patterns are not published in the book. Those are still subject to a lot of change, and have likely not even proven to work yet. For more on these maturity levels see the [Contributor Handbook](../meta/contributor-handbook.md).
-The `./book` folder contains generator scripts and some extra content required to create the gitbook.
+## How does it work technically?
-- `/.gitbook.yaml` - Holds basic configuration for the gitbook service. This never needs to be changed.
-- `/book/toc.md` - An auto-generated table of contents (ToC) for the book i.e. a list of all pages and patterns that are part of the book. The ToC is what you see on the left-hand-side menu in gitbooks.
-- `/book/generate_toc.rb` - Takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/toc_template.md`. The output is written to `/book/toc.md`.
-- `.github/workflows/book.yml` - A GitHub Action that triggers the execution of `/book/generate_toc.rb`.
-- `/book/introduction.md` - The introduction to our book. This content is what the reader sees first when they open the book. The current content is based on [README.md](../README.md). We may need to modify this content even further, to address the readers of the book more specifically, rather than the readers of our GitHub repository.
-- `/book/contribute.md` - Information about how to contribute to this book.
-- `/book/explore-patterns.md` - Dedicated page in the book that highlights the mind map of all patterns.
+We use the [gitbook.com](https://www.gitbook.com) service to host our book.
+
+The `/book` folder contains generator scripts and extra content required to create the gitbook.
+
+- `.github/workflows/book.yml` - A GitHub Action that triggers scripts to generate the book.
+- `/book/scripts/generate_toc.rb` - Generates the table of contents (ToC) for the book. It takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/en/toc_template.md`. The output is written to `/book/en/toc.md`. The ToC is what you see on the left-hand-side menu in the gitbook.
+- `/book/en/.gitbook.yaml` - Holds basic configuration for the gitbook service. This file is copied to the root of the repo, if the English book is generated.
+- `/book/en/introduction.md` - The introduction to our book. This is what the reader sees first when they open the book. *Note:* The current content is based on [README.md](../README.md).
+- `/book/en/contribute.md` - Explains how to contribute to this book.
+- `/book/en/explore-patterns.md` - Shows the mind map of all patterns. Allows readers to link to the mind map directly.
+- patterns content:
+ - The English patterns are in `/patterns`
+ - The translated patterns (e.g. for Japanese) are in `/translation/ja`
+
+The book is generated in multiple languages.
+
+The descriptions above are for the English book. You find the English content in `/book/en`.
+
+For other languages (e.g. for Japanese), the content is mirrored and translated to folders like `/book/ja`.
+
+For more on the translation process see [these translation instructions](../translation/README.md).
+
+### Triggering the book generation
+
+The book is generated in multiple languages.
+
+Depending on which **branch** a change is merged into, a different book is generated:
+
+* changes merged to `main` branch: triggers the book generation for the **English** book.
+* changes merged to `book-ja` branch: triggers the book generation for the **Japanese** book.
## Objectives of the book
@@ -33,11 +56,11 @@ There are a couple of good reasons to publish the InnerSource patterns as a gitb
* (consumers) have something that is “nicer” to read than things on GitHub
* (consumers) search for keywords across all patterns
* (consumers) export book as PDF and read on other devices
-* (consumers) have stable URLs for patterns that can be used as references in other material e.g. from the Learning Path (i.e. even if the files move in the folder structure in the GitHub repo, the URL of the pattern stay the same)
+* (consumers) have stable URLs for patterns that can be used as references in other material e.g. from the Learning Path (i.e. even if the files move in the folder structure in the GitHub repo, we can keep the URL of the pattern in the book the same)
* (producers) a motivation for pattern authors and all contributors to level up patterns from 1-initial, as only 2-structured and 3-validated are published in the book
* (producers) a motivation for us to introduce more specific quality guidelines for level 2+3, so that we can be even more proud of the content in the book :)
* (producers) learn which patterns are most interesting for readers (e.g. through Google Analytics)
[InnerSourcePatterns]: https://github.com/InnerSourceCommons/InnerSourcePatterns
[book_production]: https://patterns.innersourcecommons.org
-[book_staging]: https://innersourcecommons.gitbook.io/innersource-patterns-staging/v/book-staging/
+[book_staging]: https://innersourcecommons.gitbook.io/innersource-patterns-staging/
diff --git a/book/en/.gitbook.yaml b/book/en/.gitbook.yaml
new file mode 100644
index 000000000..ee37b0bad
--- /dev/null
+++ b/book/en/.gitbook.yaml
@@ -0,0 +1,5 @@
+root : ./
+
+structure:
+ readme: book/en/introduction.md
+ summary: book/en/toc.md
diff --git a/book/contribute.md b/book/en/contribute.md
similarity index 87%
rename from book/contribute.md
rename to book/en/contribute.md
index 07713f642..6bcee5324 100644
--- a/book/contribute.md
+++ b/book/en/contribute.md
@@ -22,10 +22,10 @@ Here a few ways in which you can contribute:
For (1) and (2) above you can simply hit the **Edit on GitHub** link that you see at the top of each page in this book. This will take you straight to the respective file in our GitHub repository, where you can suggest your changes.
-For (3) you need to clone the [InnerSourcePatterns][repo] repository, and add a new file with your suggested pattern. When making such larger contributions to this book please review our [CONTRIBUTING.md](../CONTRIBUTING.md) and also our [Contributor Handbook](../meta/contributor-handbook.md).
+For (3) you need to clone the [InnerSourcePatterns][repo] repository, and add a new file with your suggested pattern. When making such larger contributions to this book please review our [CONTRIBUTING.md](../../CONTRIBUTING.md) and also our [Contributor Handbook](../../meta/contributor-handbook.md).
## License of Contributions
-The contents of this repository are licensed under [CC-BY-SA-4.0](../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.
+The contents of this repository are licensed under [CC-BY-SA-4.0](../../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.
[repo]: https://github.com/InnerSourceCommons/InnerSourcePatterns
diff --git a/book/explore-patterns.md b/book/en/explore-patterns.md
similarity index 92%
rename from book/explore-patterns.md
rename to book/en/explore-patterns.md
index 1fc8a53ef..bdc6e109a 100644
--- a/book/explore-patterns.md
+++ b/book/en/explore-patterns.md
@@ -6,7 +6,7 @@ Now how to make it easy for readers to discover the patterns that can help them
For this purpose we provide this mind map. It **categorizes patterns based on the different phases of an InnerSource Program**, and the challenges that might appear in the respective phases.
-
+
## Improve this Mind Map
diff --git a/book/innersource-patterns-book-cover.jpg b/book/en/innersource-patterns-book-cover.jpg
similarity index 100%
rename from book/innersource-patterns-book-cover.jpg
rename to book/en/innersource-patterns-book-cover.jpg
diff --git a/book/introduction.md b/book/en/introduction.md
similarity index 94%
rename from book/introduction.md
rename to book/en/introduction.md
index 64502aac4..944d4dfef 100644
--- a/book/introduction.md
+++ b/book/en/introduction.md
@@ -1,10 +1,10 @@
# Introduction
-
+
{% hint style="info" %}
You are reading an early release of the InnerSource Patterns book and may still find broken links, spelling mistakes, or other errors.
-Please help us to fix them to produce the best book possible :). Learn how to [contribute to this book](../book/contribute.md).
+Please help us to fix them to produce the best book possible :). Learn how to [contribute to this book](contribute.md).
{% endhint %}
Welcome to the **InnerSource Patterns Book**.
@@ -15,7 +15,7 @@ The [InnerSource Commons](http://innersourcecommons.org) has collected these pat
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.
-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.md)!
+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](contribute.md)!
## What is InnerSource?
@@ -35,7 +35,7 @@ Patterns can provide a way for the InnerSource Commons participants to concisely
* [`What are patterns?` Youtube videos](http://bit.ly/innersource_patterns_videos) - Watch a set of 2-5 min youtube videos explaining InnerSource Patterns
* [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).
-* [Pattern Template](../meta/pattern-template.md) - View a skeleton inner source pattern to get an idea on what goes into a new pattern!
+* [Pattern Template](../../meta/pattern-template.md) - View a skeleton inner source pattern to get an idea on what goes into a new pattern!
* [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).
## How can you use InnerSource Patterns?
diff --git a/book/en/toc.md b/book/en/toc.md
new file mode 100644
index 000000000..6974018d4
--- /dev/null
+++ b/book/en/toc.md
@@ -0,0 +1,55 @@
+# Table of Contents
+
+
+
+
+
+* [Introduction](./introduction.md)
+* [Table of Contents](./toc.md)
+* [Explore Patterns](./explore-patterns.md)
+* [Contribute to this book](./contribute.md)
+
+
+
+## Patterns
+
+* [30 Day Warranty](../../patterns/2-structured/30-day-warranty.md) - When accepting contributions from outside of your own team, there is a natural aversion to taking responsibility for code not written by the team itself. Through the 30 Day Warranty the contributing team consents to provide bug fixes to the receiving team, which will increase the level of trust between both teams and makes it more likely that contributions get accepted.
+* [Common Requirements](../../patterns/2-structured/common-requirements.md) - Common code in a shared repository isn't meeting the needs of all the project-teams that want to use it; this is solved through requirements alignment and refactoring.
+* [Communication Tooling](../../patterns/2-structured/project-setup/communication-tooling.md) - An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project team. The idea is to set up and document standard communication tooling that allows for discussions to become visible, archived and searchable.
+* [Contracted Contributor](../../patterns/2-structured/contracted-contributor.md) - Associates wanting to contribute to InnerSource are discouraged from doing so by their line management. Relief is provided by formal contracts and agreements.
+* [Core Team](../../patterns/2-structured/core-team.md) - Even when an InnerSource project is widely needed, contributions and usage may be hindered because the project is difficult to work with. Establish a core team that is dedicated to take care of the project's fundamental items. Their work enables contributors to add and use the features that provide value to their scenarios.
+* [Cross-Team Project Valuation](../../patterns/2-structured/crossteam-project-valuation.md) - It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it.
+* [Dedicated Community Leader](../../patterns/2-structured/dedicated-community-leader.md) - Select people with both communications and technical skills to lead the communities to ensure success in starting an InnerSource initiative.
+* [Document your Guiding Principles](../../patterns/2-structured/document-your-guiding-principles.md) - The usual InnerSource explanation of "applying open source best practices inside an organisation" does not work well with people lacking an open source background. As a remedy the most important principles of InnerSource get documented and published widely.
+* [Extensions for Sustainable Growth](../../patterns/2-structured/extensions-for-sustainable-growth.md) - An InnerSource project is receiving too many contributions, making maintenance difficult. By offering an extension mechanism outside of the core project, the maintainers enable scaling of project capabilities with minimal cost and maintenance overhead.
+* [Gig Marketplace](../../patterns/2-structured/gig-marketplace.md) - Establish a marketplace by creating an intranet website that lists specific InnerSource project needs as "Gigs" with explicit time and skill requirements. This will enable managers to better understand their employee’s time commitment and professional benefits thereby increasing the likelihood of garnering approval to make InnerSource contributions.
+* [InnerSource License](../../patterns/2-structured/innersource-license.md) - Two legal entities that belong to the same organization want to share software source code with each other but they are concerned about the implications in terms of legal liabilities or cross-company accounting.
+* [InnerSource Portal](../../patterns/2-structured/innersource-portal.md) - Potential contributors cannot easily discover InnerSource projects that they are interested in. By creating an intranet website that indexes all available InnerSource project information you enable contributors to learn about projects that might interest them and InnerSource project owners to attract an outside audience.
+* [Issue Tracker Use Cases](../../patterns/2-structured/project-setup/issue-tracker.md) - The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design.
+* [Maturity Model](../../patterns/2-structured/maturity-model.md) - Teams have started adopting InnerSource. The practice is spreading to multiple departments. However, the understanding of what constitutes an InnerSource project varies. The solution is to provide a maturity model to allow for teams to go through a self check and discover patterns and practices that they are not yet aware of.
+* [Praise Participants](../../patterns/2-structured/praise-participants.md) - After an inner source contribution, it's important to thank the contributor for their time and effort. This pattern gives guidance that not only effectively acknowledges the contribution but also engenders further engagement from the contributor and others.
+* [Repository Activity Score](../../patterns/2-structured/repository-activity-score.md) - Potential contributors want to find active InnerSource projects in need of their help. By calculating a repository activity score for each project, a ranked list of projects can be created (e.g. on the InnerSource Portal), so that potential contributors can more easily determine which project they want to contribute to.
+* [Review Committee](../../patterns/2-structured/review-committee.md) - The InnerSource working model is a radical departure from more traditional approaches, for developers and managers alike. By establishing a review committee as an interface between the InnerSource initiative and all senior managers of business units participating in it, the latter are more likely to familiarise themselves with the initiative and support it, as it affords them a certain level of oversight and control without fostering micromanagement.
+* [Service vs. Library](../../patterns/2-structured/service-vs-library.md) - Teams in a DevOps environment may be reluctant to work across team boundaries on common code bases due to ambiguity over who will be responsible for responding to service downtime. The solution is to realize that often it's possible to either deploy the same service in independent environments with separate escalation chains in the event of service downtime or factor a lot of shared code out into one library and collaborate on that.
+* [Standard Base Documentation](../../patterns/2-structured/project-setup/base-documentation.md) - New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own.
+* [Start as an Experiment](../../patterns/2-structured/start-as-experiment.md) - Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative.
+* [Transparent Cross-Team Decision Making using RFCs](../../patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md) - InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties.
+* [Trusted Committer](../../patterns/2-structured/trusted-committer.md) - Many InnerSource projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations, project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions.
+
+## Appendix
+
+* [Pattern Template](../../meta/pattern-template.md)
+* Extras
+ * [README Template](../../patterns/2-structured/project-setup/templates/README-template.md)
+ * [CONTRIBUTING Template](../../patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md)
+
+## Resources
+
+* [This book on GitHub](https://github.com/InnerSourceCommons/InnerSourcePatterns)
+* [InnerSource Commons](http://innersourcecommons.org)
diff --git a/book/en/toc_template.md b/book/en/toc_template.md
new file mode 100644
index 000000000..d961c2219
--- /dev/null
+++ b/book/en/toc_template.md
@@ -0,0 +1,34 @@
+# Table of Contents
+
+
+
+
+
+* [Introduction](./introduction.md)
+* [Table of Contents](./toc.md)
+* [Explore Patterns](./explore-patterns.md)
+* [Contribute to this book](./contribute.md)
+
+
+
+## Patterns
+
+<
-
-## Patterns
-
-* [30 Day Warranty](../patterns/2-structured/30-day-warranty.md) - When accepting contributions from outside of your own team, there is a natural aversion to taking responsibility for code not written by the team itself. Through the 30 Day Warranty the contributing team consents to provide bug fixes to the receiving team, which will increase the level of trust between both teams and makes it more likely that contributions get accepted.
-* [Common Requirements](../patterns/2-structured/common-requirements.md) - Common code in a shared repository isn't meeting the needs of all the project-teams that want to use it; this is solved through requirements alignment and refactoring.
-* [Communication Tooling](../patterns/2-structured/project-setup/communication-tooling.md) - An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project team. The idea is to set up and document standard communication tooling that allows for discussions to become visible, archived and searchable.
-* [Contracted Contributor](../patterns/2-structured/contracted-contributor.md) - Associates wanting to contribute to InnerSource are discouraged from doing so by their line management. Relief is provided by formal contracts and agreements.
-* [Core Team](../patterns/2-structured/core-team.md) - Even when an InnerSource project is widely needed, contributions and usage may be hindered because the project is difficult to work with. Establish a core team that is dedicated to take care of the project's fundamental items. Their work enables contributors to add and use the features that provide value to their scenarios.
-* [Cross-Team Project Valuation](../patterns/2-structured/crossteam-project-valuation.md) - It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it.
-* [Dedicated Community Leader](../patterns/2-structured/dedicated-community-leader.md) - Select people with both communications and technical skills to lead the communities to ensure success in starting an InnerSource initiative.
-* [Gig Marketplace](../patterns/2-structured/gig-marketplace.md) - Establish a marketplace by creating an intranet website that lists specific InnerSource project needs as "Gigs" with explicit time and skill requirements. This will enable managers to better understand their employee’s time commitment and professional benefits thereby increasing the likelihood of garnering approval to make InnerSource contributions.
-* [InnerSource License](../patterns/2-structured/innersource-license.md) - Two legal entities that belong to the same organization want to share software source code with each other but they are concerned about the implications in terms of legal liabilities or cross-company accounting.
-* [InnerSource Portal](../patterns/2-structured/innersource-portal.md) - Create an intranet website that indexes all available InnerSource project information. This will enable potential contributors to more easily learn about projects that might interest them and for InnerSource project owners to attract an outside audience.
-* [Issue Tracker Use Cases](../patterns/2-structured/project-setup/issue-tracker.md) - The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design.
-* [Maturity Model](../patterns/2-structured/maturity-model.md) - Teams have started adopting InnerSource. The practice is spreading to multiple departments. However, the understanding of what constitutes an InnerSource project varies. The solution is to provide a maturity model to allow for teams to go through a self check and discover patterns and practices that they are not yet aware of.
-* [Praise Participants](../patterns/2-structured/praise-participants.md) - After an inner source contribution, it's important to thank the contributor for their time and effort. This pattern gives guidance that not only effectively acknowledges the contribution but also engenders further engagement from the contributor and others.
-* [Repository Activity Score](../patterns/2-structured/repository-activity-score.md) - Potential contributors want to find active InnerSource projects in need of their help. By calculating a repository activity score for each project, a ranked list of projects can be created (e.g. on the InnerSource Portal), so that potential contributors can more easily determine which project they want to contribute to.
-* [Review Committee](../patterns/2-structured/review-committee.md) - The InnerSource working model is a radical departure from more traditional approaches, for developers and managers alike. By establishing a review committee as an interface between the InnerSource initiative and all senior managers of business units participating in it, the latter are more likely to familiarise themselves with the initiative and support it, as it affords them a certain level of oversight and control without fostering micromanagement.
-* [Service vs. Library](../patterns/2-structured/service-vs-library.md) - Teams in a DevOps environment may be reluctant to work across team boundaries on common code bases due to ambiguity over who will be responsible for responding to service downtime. The solution is to realize that often it's possible to either deploy the same service in independent environments with separate escalation chains in the event of service downtime or factor a lot of shared code out into one library and collaborate on that.
-* [Standard Base Documentation](../patterns/2-structured/project-setup/base-documentation.md) - New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own.
-* [Start as an Experiment](../patterns/2-structured/start-as-experiment.md) - Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative.
-* [Transparent Cross-Team Decision Making using RFCs](../patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md) - InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties.
-* [Trusted Committer](../patterns/2-structured/trusted-committer.md) - Many InnerSource projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations, project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions.
-
-## Appendix
-
-* [Pattern Template](../meta/pattern-template.md)
-* Extras
- * [README Template](../patterns/2-structured/project-setup/templates/README-template.md)
- * [CONTRIBUTING Template](../patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md)
-
-## Resources
-
-* [This book on GitHub](https://github.com/InnerSourceCommons/InnerSourcePatterns)
-* [InnerSource Commons](http://innersourcecommons.org)
diff --git a/book/toc_template.md b/book/toc_template.md
deleted file mode 100644
index a00058e11..000000000
--- a/book/toc_template.md
+++ /dev/null
@@ -1,33 +0,0 @@
-
-
-
-
-# Table of Contents
-
-* [Table of Contents](../book/toc.md)
-* [Explore Patterns](../book/explore-patterns.md)
-* [Contribute to this book](../book/contribute.md)
-
-
-
-## Patterns
-
-<