:cn: Chinese: Content Consistency Issue

[github-actions[bot]]

i18n Contents Consistency Issue

The following files may have consistency issues with the English version. Please check and update the files.

This issue is created when any of the English patterns have changed (in folder ). It compares the git update history to let you know what updates are overdue. The issue should be closed when the update is complete.

Communication Tooling (patterns/2-structured/communication-tooling.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/communication-tooling.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/communication-tooling.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **3** days. ```diff # diff --git a/patterns/2-structured/communication-tooling.md b/patterns/2-structured/communication-tooling.md # new file mode 100644 # index 0000000..08b1a33 # --- /dev/null +++ b/patterns/2-structured/communication-tooling.md @@ -0,0 +1,96 @@ +## Title + +Communication Tooling + +## Patlet + +The users of an InnerSource project have trouble getting help and getting in touch with the host team. +By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. + +## Problem + +A team is open to receiving contributions from downstream users of their +component. Coordination and communication happens in an ad hoc fashion though +leading to incoherent information being shared, delays in answers received, +contributors pinging multiple host team members before receiving a definitive +answer. + +## Context + +- A team depends on another team's component. +- It would like to make contributions to that component. +- Even when it happens in writing, communication happens in a 1-on-1 fashion. + +## Forces + +- The host team is interested in receiving contributions and willing to mentor contributors. +- Teams have a strong verbal communication culture and are inexperienced with setting up project specific asynchronous communication channels. +- Communication channels may be aligned with specific groups that should be reached but not by communication purpose. + +## Solution + +The host team should provide company-public, archived, searchable, linkable communication channels that anyone in the company can subscribe to, as there are measurable benefits to supporting open, written communications channels. + +The goal when streamlining communication channels for InnerSource projects +should be to align communication around topics, not around certain sets of +people. + +A project should set up the following communication tooling: + +1. **a dedicated issue tracker** where structured communication, decision-making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow. For further applications of the issue tracker see [Issue Tracker Use Cases](./issue-tracker.md). +2. **public discussion channel(s)** that come with less rigid a structure. Typically, this will be mailing lists, online forums, Q&A systems or even archived chat channels. Usually it is enough to start with just one channel for the project. If traffic increases too much it is helpful to split discussions about project usage from discussions about project development. +3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](./trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. + +While communication can happen outside of those written channels, as much information as possible should be brought back to the asynchronous channels. + +All communication channels should be documented in the project `README.md`. For more details on the use of this file see [Standard Base Documentation](./base-documentation.md). + +The host team members need to make an effort to direct questions that they receive personally (e.g. via email or private chat messages) back to official communication channels. + + + +## Resulting Context + +Setting up and consistently using official asynchronous communication channels +helps create a base level of [passive documentation](https://www.oreilly.com/library/view/understanding-the-innersource/9781491986899/ch04.html) that can be referenced again when similar questions come up again. + +With communication happening in the open others can easily follow project +progress and get active contributing. Others lurking and reading lowers the +barrier to get involved raising the likelihood of receiving contributions. + +With questions being answered in public more people can add their perspective +leading to a complete picture - this includes not only host team members, +but also users of the project. + +Keeping communication in asynchronous channels allows for participants on +different schedules - either due to different time zones or due to different +routines, meeting schedules, team routines - to meaningfully contribute to +the project. + +Answering questions in those channels means that not only other team members +can listen in and provide additional information, it also means that other +users with the same question see (or later find) the previous answer leading +to a lower need to repeat explanations. + +## Known Instances + +* Europace AG +* Paypal Inc. +* Mercado Libre + +## Authors + +Isabel Drost-Fromm + +## Acknowledgment + +Sebastian Spier (for the visual) + +## Status + +* Structured +* Drafted in December 2019. + +## Credits + +[People](https://storyset.com/people) illustrations by Storyset ```

Standard Base Documentation (patterns/2-structured/base-documentation.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/base-documentation.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/base-documentation.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **3** days. ```diff # diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md # new file mode 100644 # index 0000000..bd20b82 # --- /dev/null +++ b/patterns/2-structured/base-documentation.md @@ -0,0 +1,161 @@ +## Title + +Standard Base Documentation + +## Patlet + +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`/`COMMUNICATION.md` enables a +self service process for new contributors, so that they can find the answers to +the most common questions on their own. + +## Problem + +A team wants to share either a freshly started or a preexisting project with +the wider organization and receive contributions to it. Potential contributors +often are lost: They are failing to identify the team's preferred communication +channels. They have trouble quickly making a judgment about whether a new +feature makes sense to be added or not. They have a hard time understanding +exactly which colleagues are currently actively maintaining the project. + +## Context + +A project is to be shared with others as an InnerSource project. In order for +others to be able to understand what the project is about as well as how to +contribute, the project needs to provide some base level documentation. So far +the project is lacking either all documentation or some aspects needed for users +to try it out in a self-service manner as well as for contributors to get up to +speed quickly. + +## Forces + +- The project was converted into an InnerSource project only recently. Before, users were either only internal or on-boarded in personal face-to-face sessions. Equally, people working on the project went through personal on-boarding sessions which do not scale with growing numbers of contributors or remote contributors. As a result, self service documentation is lacking. +- The project was newly created as an InnerSource project. However the host team lacks experience with InnerSource. As a result they need guidance on which information to include in their documentation, where to put that documentation so others can find it and which types of readers to address in their documentation. +- The project was converted into an InnerSource project only recently, the host team has limited experience with InnerSource. As a result, existing documentation addresses a lot of technical aspects. It does not cover communication, coordination, information needed to facilitate transparent planning. +- The project was converted into an InnerSource project only recently. As a result, a lot of implicit knowledge that exists within the team is neither written down nor obvious to contributors. +- A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing documentation (and keeping it up to date) requires a time investment. Even if the host team relies on contributors to help with lacking documentation, those contributions still need time to review. +- Project members are spending a lot of time answering getting started questions. Maintaining a comprehensive database of what could be considered support questions requires a lot of time and effort though. +- Different teams within the organization have diverging standards for how to format source code and which software patterns to use. As a result contributions often end up getting re-written to a large part or even entirely. Standardizing all of that and enforcing the standard often would require a lot of time and work. +- The added work for repeated explanations and re-writes diminishes the usefulness of the InnerSource approach. +- Frequent escalations due to extra work and delays due to re-writes lead to a big cheese situation. + +## Solution + +Address the need for clearer documentation for new contributors. The goal when +creating this documentation should be to make getting started as much a self +service process as possible with frequently asked questions answered in standard +documentation format. + +### README.md + +If it does not yet exist, create a `README.md` for your project. It should +contain: + +* The [mission of the project](https://producingoss.com/en/producingoss.html#mission-statement) in as a concise format as possible. It should answer what the project's purpose is and enable contributors to make a good first guess whether a suggested feature will likely be in scope for the project, or not. +* A "Getting Started" section for downstream users of the project. It should explain how to setup/ integrate the project artifacts as well as an explanation of some of the first typical steps for first time users. +* Deeper documentation for project users - or a link to that. +* Documentation needed for making modifications to the project - or a link to that. +* Documentation on how to contribute to the project - or a link to that. +* A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used. +* A "Who we are" section explaining who the [Trusted Committers](trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. +* An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists. + + + +### CONTRIBUTING.md + +If the explanation of the steps to make a contribution are too involved, create +a separate `CONTRIBUTING.md` document. This document should answer frequently +asked questions that contributors have asked in the past. There is no need to +provide a comprehensive book up front. Rather, share information that has proven +needed by contributors. Likely it will touch upon one or more of the following +topics: + +* How to checkout the project source code from version control. +* How to make modifications to the project (potentially including information on coding guidelines). +* How to build the project. +* How to run tests to make sure the above modifications aren't introducing new bugs. +* How to submit your modifications back to the project. +* Some information on which turnaround time to expect for modifications made. + + + +### COMMUNICATION.md + +Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. + +Sections in the `COMMUNICATION.md` include points of contact for incoming communications and information about outgoing communications from the project's ownership team. See some examples below. + +Points of contact for incoming communication and how to contact those users: + +* Reporting a bug +* Following up on a PR +* Feature requests +* Questions about documentation +* Escalations + +How and when the team communicates outbound with users and how to get added to those communications: + +* Planned and unplanned outages +* Feature releases +* Code freezes +* Breaking changes + +There are many of good examples for how to write a `README.md` and what kind +of information to include in a `CONTRIBUTING.md` file in various open source projects. +Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), +[Open Source Guide from GitHub](https://opensource.guide/) as well as +the book [Producing Open Source](https://producingoss.com/en/producingoss.html) +all have valuable information on what kind of information to provide. While +Producing Open Source does not have a chapter on writing a good README per se, +the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) +does provide a fairly extensive list of things that fellow host team members, +users and contributors will need. InnerSource projects likely will not cover all +of those aspects right from the start, the list itself is helpful for +inspiration for what one could cover. + +In addition to that, this pattern comes with three very basic templates to get you +started right away: [README-template.md](templates/README-template.md), +[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). + +## Resulting Context + +* The time for contributors to get up to speed is significantly reduced. +* Time spent on answering initial questions for [Trusted Committers](trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. +* Escalations due to misunderstandings and misalignment are significantly reduced. + +## Known Instances + +* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) +* Paypal Inc. +* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). +* Analog Devices Inc. +* Airbus + +## Authors + +* Isabel Drost-Fromm + +## Acknowledgments + +* Katie Schueths - for adding the `COMMUNICATION.md` concept + +## Alias + +Provide standard base documentation through a README + +## Status + +* Structured +* Drafted in December 2019. + +## References + +* [README-template.md](templates/README-template.md) and +* [CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md) + +## Credits + +[Web](https://storyset.com/web) and [People](https://storyset.com/people) illustrations by Storyset ```

30 Day Warranty (patterns/2-structured/30-day-warranty.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/30-day-warranty.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **3** days. ```diff # diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md # index 7c2ab75..ce93a1b 100644 # --- a/patterns/2-structured/30-day-warranty.md # +++ b/patterns/2-structured/30-day-warranty.md @@ -34,7 +34,7 @@ Address the fears of both the receiving and the contributing teams by establishi Note that the warranty period could be 45, 60, or 100 days too. The duration may vary based upon the constraints of the project, the software life cycle of the project, commitments to customers, and other factors. -In addition it helps to provide clear [contribution guidelines](./project-setup/base-documentation.md), spelling out the expectations of the receiving team and the contributing team. +In addition it helps to provide clear [contribution guidelines](./base-documentation.md), spelling out the expectations of the receiving team and the contributing team.  ```

Maturity Model (patterns/2-structured/maturity-model.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/maturity-model.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/maturity-model.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md # index 8e41062..629c2e4 100644 # --- a/patterns/2-structured/maturity-model.md # +++ b/patterns/2-structured/maturity-model.md @@ -213,6 +213,7 @@ long term. * Entelgy * Zylk * Bitergia +* Airbus ## Authors ```

Repository Activity Score (patterns/2-structured/repository-activity-score.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/repository-activity-score.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/repository-activity-score.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **3** days. ```diff # diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md # index 27421a6..dae8f3e 100644 # --- a/patterns/2-structured/repository-activity-score.md # +++ b/patterns/2-structured/repository-activity-score.md @@ -115,7 +115,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances * Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). -* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./project-setup/base-documentation.md) and the [InnerSource License](./innersource-license.md). +* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./base-documentation.md) and the [InnerSource License](./innersource-license.md). ## Status ```

InnerSource License (patterns/2-structured/innersource-license.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-license.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/innersource-license.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...5e711f0133f5f58ab98e4c03b0475c63036e37c8) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md # index 54b5c55..169ea8a 100644 # --- a/patterns/2-structured/innersource-license.md # +++ b/patterns/2-structured/innersource-license.md @@ -32,6 +32,7 @@ At the time of sharing the source code, it can not be reliably predicted what th - Freedom over using the software leads to competition, and spread of ownership - There are legal contracts in place which cover the sharing of source code. These contracts are not standardized, so they create additional effort in negotiating and understanding for every project. The existing contracts may also not allow sharing source code in an open enough sense to support a true InnerSource approach. - Alternatively, there are no legal contracts in place but source code is shared informally. That might create uncertainty in cases where clarity about ownership and rights and obligations is needed. +- Choosing a restrictive and/or copyleft license can constitute a barrier for InnerSource adoption. Specifically, limiting publication to the organisation might require a costly relicensing procedure prior to transitioning to Open Source. ## Solutions @@ -51,6 +52,12 @@ The license simplifies the conversations within our organization about sharing s ## Known Instances +- **DB Systel** +- **Robert Bosch GmbH** +- **Airbus** + +## DB Systel + DB Systel created their own InnerSource License, see [DB Inner Source License][db-inner-source-license]. They used the [EUPL][eupl], as that offered an open source like starting point, and then worked out the constraints and additional rules required in their specific organizational context. The first legal entities (companies) within the DB AG are using their InnerSource License. @@ -66,6 +73,8 @@ The mentioned collaboration challenges include: It is worth mentioning that so far the software shared under this InnerSource license is mostly tooling, infrastructure, and tools lower in the stack. +## Airbus + Airbus created ad hoc InnerSource licenses to enable InnerSource way of working within a large part of the group. ## Status ```

Issue Tracker Use Cases (patterns/2-structured/issue-tracker.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/issue-tracker.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/issue-tracker.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **3** days. ```diff # diff --git a/patterns/2-structured/issue-tracker.md b/patterns/2-structured/issue-tracker.md # new file mode 100644 # index 0000000..ffbda05 # --- /dev/null +++ b/patterns/2-structured/issue-tracker.md @@ -0,0 +1,60 @@ +## Title + +Issue Tracker Use Cases + +## Patlet + +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. + +## Problem + +A team develops a component that many teams in the organization depend on. It +uses a standard issue tracker for tracking open bugs and feature requests. +However, the context in each entry is very limited. As a result potential +contributors have no way of knowing what change exactly each issue is talking +about. + +## Context + +The InnerSource project tooling is all setup. However, the project issue tracker +is mainly used for sharing progress. In InnerSource projects there are many more +use cases that an issue tracker can be used for that make remote, asynchronous +communication easier. + +## Forces + +- Contributors would like to understand whether the feature that they are missing is already on the roadmap. With a lot of context missing in issues though it is impossible to decide whether existing issues match the contributing team's needs. +- As a result a lot of duplicate issues are being opened that the host team has to deal with. +- As context in open issues is so limited contributors are unable to help the host team by implementing some easier issues that are open already. As a result a lot of work remains in the hands of the host team. +- With a strong focus on verbal communication it is impossible to discern after a couple months or years why a certain feature was being chosen for implementation. As a result refactorings, in particular simplifying the component becomes an exercise in project archaeology and brain picking of people who remember what was discussed. + +## Solution + +Embrace the "written over verbal" philosophy not only for pure software +development but also during the planning phase of new features: + +- For bugs, planned features and feature ideas create separate issues. In each of those include as much information as possible so that potential external contributors are able to understand the context. Ideally, in particular for easier changes, include enough information for external contributors to support the host team by implementing the functionality in question. +- Potentially use the issue tracker as a channel to ask questions. This is in particular helpful if you are lacking other communication sources to tackle user questions. +- Make use of tags and categories in order to distinguish issues used for different purposes. +- For starting a brainstorming session asynchronously, open an issue for gathering ideas. When discussion is starting to calm down, summarize the points identified in this issue in a separate document. Post that for review as a pull request to drill deeper into individual points that still need clarification. The resulting document can be used to publish the results in other appropriate channels as well as for future reference. +- Most issue tracker implementations allow for issue templates. Make use of those not only to collect commonly needed information for bug reports but also include hints about what kind of information is needed for the other usage types. + +## Resulting Context + +- Making more use of the project's issue tracker for communication enables external contributors to follow along and make better decisions on what to contribute. +- A focus on structured written communication enables host team members to participate remotely. +- Consistently communicating in writing means that passive documentation on project decisions accumulates as a by-product instead of needing added attention. +- Consistently using public communication channels leads to more humans following a discussion. This means that there are more knowledgeable humans that can answer questions, chime in on open issues, or point out flaws in planned features that would otherwise be found only much later. +- Moving discussions to a public discussion medium creates an opportunity for potential future contributors to lurk, follow along, get comfortable and learn the ways of the project long before they have the first need to get involved. + +## Known Instances + +* Europace AG - See blog post [Issue Use Cases](https://tech.europace.de/post/using-issues-for-asking-questions-and-tracking-work/) + +## Authors + +Isabel Drost-Fromm + +## Status + +Structured ```

Dedicated Community Leader (patterns/2-structured/dedicated-community-leader.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/dedicated-community-leader.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/dedicated-community-leader.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md # index 91f3c3d..8f5235d 100644 # --- a/patterns/2-structured/dedicated-community-leader.md # +++ b/patterns/2-structured/dedicated-community-leader.md @@ -59,6 +59,7 @@ Having excellent and dedicated community leaders is a precondition for the succe ## Known Instances * _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. +* _Airbus_. A data scientist wanted to improve the collaboration with peers in the group and found: i) many developers (beyond data science) wanted that too and were happy someone was taking care of the issue, and ii) support from line manager and middle management to eventually act as the _de facto_ community leader, on top of his regular line of duty. ## Alias ```

Start as an Experiment (patterns/2-structured/start-as-experiment.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/start-as-experiment.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/start-as-experiment.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md # index 53326df..56e0c7d 100644 # --- a/patterns/2-structured/start-as-experiment.md # +++ b/patterns/2-structured/start-as-experiment.md @@ -54,6 +54,7 @@ Finally, starting as an experiment makes it much easier to sidestep regulations ## Known Instances - Robert Bosch GmbH (globally distributed software development) +- Airbus: the data science community collaborated on shared Python libraries that eventually lead to a group-wide InnerSource scheme for any software. ## Status ```

[github-actions[bot]]

i18n Contents Consistency Issue

The following files may have consistency issues with the English version. Please check and update the files.

This issue is created when any of the English patterns have changed (in folder ). It compares the git update history to let you know what updates are overdue. The issue should be closed when the update is complete.

Communication Tooling (patterns/2-structured/communication-tooling.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/communication-tooling.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/communication-tooling.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/communication-tooling.md b/patterns/2-structured/communication-tooling.md # new file mode 100644 # index 0000000..08b1a33 # --- /dev/null +++ b/patterns/2-structured/communication-tooling.md @@ -0,0 +1,96 @@ +## Title + +Communication Tooling + +## Patlet + +The users of an InnerSource project have trouble getting help and getting in touch with the host team. +By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. + +## Problem + +A team is open to receiving contributions from downstream users of their +component. Coordination and communication happens in an ad hoc fashion though +leading to incoherent information being shared, delays in answers received, +contributors pinging multiple host team members before receiving a definitive +answer. + +## Context + +- A team depends on another team's component. +- It would like to make contributions to that component. +- Even when it happens in writing, communication happens in a 1-on-1 fashion. + +## Forces + +- The host team is interested in receiving contributions and willing to mentor contributors. +- Teams have a strong verbal communication culture and are inexperienced with setting up project specific asynchronous communication channels. +- Communication channels may be aligned with specific groups that should be reached but not by communication purpose. + +## Solution + +The host team should provide company-public, archived, searchable, linkable communication channels that anyone in the company can subscribe to, as there are measurable benefits to supporting open, written communications channels. + +The goal when streamlining communication channels for InnerSource projects +should be to align communication around topics, not around certain sets of +people. + +A project should set up the following communication tooling: + +1. **a dedicated issue tracker** where structured communication, decision-making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow. For further applications of the issue tracker see [Issue Tracker Use Cases](./issue-tracker.md). +2. **public discussion channel(s)** that come with less rigid a structure. Typically, this will be mailing lists, online forums, Q&A systems or even archived chat channels. Usually it is enough to start with just one channel for the project. If traffic increases too much it is helpful to split discussions about project usage from discussions about project development. +3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](./trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. + +While communication can happen outside of those written channels, as much information as possible should be brought back to the asynchronous channels. + +All communication channels should be documented in the project `README.md`. For more details on the use of this file see [Standard Base Documentation](./base-documentation.md). + +The host team members need to make an effort to direct questions that they receive personally (e.g. via email or private chat messages) back to official communication channels. + + + +## Resulting Context + +Setting up and consistently using official asynchronous communication channels +helps create a base level of [passive documentation](https://www.oreilly.com/library/view/understanding-the-innersource/9781491986899/ch04.html) that can be referenced again when similar questions come up again. + +With communication happening in the open others can easily follow project +progress and get active contributing. Others lurking and reading lowers the +barrier to get involved raising the likelihood of receiving contributions. + +With questions being answered in public more people can add their perspective +leading to a complete picture - this includes not only host team members, +but also users of the project. + +Keeping communication in asynchronous channels allows for participants on +different schedules - either due to different time zones or due to different +routines, meeting schedules, team routines - to meaningfully contribute to +the project. + +Answering questions in those channels means that not only other team members +can listen in and provide additional information, it also means that other +users with the same question see (or later find) the previous answer leading +to a lower need to repeat explanations. + +## Known Instances + +* Europace AG +* Paypal Inc. +* Mercado Libre + +## Authors + +Isabel Drost-Fromm + +## Acknowledgment + +Sebastian Spier (for the visual) + +## Status + +* Structured +* Drafted in December 2019. + +## Credits + +[People](https://storyset.com/people) illustrations by Storyset ```

Standard Base Documentation (patterns/2-structured/base-documentation.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/base-documentation.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/base-documentation.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md # new file mode 100644 # index 0000000..bd20b82 # --- /dev/null +++ b/patterns/2-structured/base-documentation.md @@ -0,0 +1,161 @@ +## Title + +Standard Base Documentation + +## Patlet + +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`/`COMMUNICATION.md` enables a +self service process for new contributors, so that they can find the answers to +the most common questions on their own. + +## Problem + +A team wants to share either a freshly started or a preexisting project with +the wider organization and receive contributions to it. Potential contributors +often are lost: They are failing to identify the team's preferred communication +channels. They have trouble quickly making a judgment about whether a new +feature makes sense to be added or not. They have a hard time understanding +exactly which colleagues are currently actively maintaining the project. + +## Context + +A project is to be shared with others as an InnerSource project. In order for +others to be able to understand what the project is about as well as how to +contribute, the project needs to provide some base level documentation. So far +the project is lacking either all documentation or some aspects needed for users +to try it out in a self-service manner as well as for contributors to get up to +speed quickly. + +## Forces + +- The project was converted into an InnerSource project only recently. Before, users were either only internal or on-boarded in personal face-to-face sessions. Equally, people working on the project went through personal on-boarding sessions which do not scale with growing numbers of contributors or remote contributors. As a result, self service documentation is lacking. +- The project was newly created as an InnerSource project. However the host team lacks experience with InnerSource. As a result they need guidance on which information to include in their documentation, where to put that documentation so others can find it and which types of readers to address in their documentation. +- The project was converted into an InnerSource project only recently, the host team has limited experience with InnerSource. As a result, existing documentation addresses a lot of technical aspects. It does not cover communication, coordination, information needed to facilitate transparent planning. +- The project was converted into an InnerSource project only recently. As a result, a lot of implicit knowledge that exists within the team is neither written down nor obvious to contributors. +- A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing documentation (and keeping it up to date) requires a time investment. Even if the host team relies on contributors to help with lacking documentation, those contributions still need time to review. +- Project members are spending a lot of time answering getting started questions. Maintaining a comprehensive database of what could be considered support questions requires a lot of time and effort though. +- Different teams within the organization have diverging standards for how to format source code and which software patterns to use. As a result contributions often end up getting re-written to a large part or even entirely. Standardizing all of that and enforcing the standard often would require a lot of time and work. +- The added work for repeated explanations and re-writes diminishes the usefulness of the InnerSource approach. +- Frequent escalations due to extra work and delays due to re-writes lead to a big cheese situation. + +## Solution + +Address the need for clearer documentation for new contributors. The goal when +creating this documentation should be to make getting started as much a self +service process as possible with frequently asked questions answered in standard +documentation format. + +### README.md + +If it does not yet exist, create a `README.md` for your project. It should +contain: + +* The [mission of the project](https://producingoss.com/en/producingoss.html#mission-statement) in as a concise format as possible. It should answer what the project's purpose is and enable contributors to make a good first guess whether a suggested feature will likely be in scope for the project, or not. +* A "Getting Started" section for downstream users of the project. It should explain how to setup/ integrate the project artifacts as well as an explanation of some of the first typical steps for first time users. +* Deeper documentation for project users - or a link to that. +* Documentation needed for making modifications to the project - or a link to that. +* Documentation on how to contribute to the project - or a link to that. +* A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used. +* A "Who we are" section explaining who the [Trusted Committers](trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. +* An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists. + + + +### CONTRIBUTING.md + +If the explanation of the steps to make a contribution are too involved, create +a separate `CONTRIBUTING.md` document. This document should answer frequently +asked questions that contributors have asked in the past. There is no need to +provide a comprehensive book up front. Rather, share information that has proven +needed by contributors. Likely it will touch upon one or more of the following +topics: + +* How to checkout the project source code from version control. +* How to make modifications to the project (potentially including information on coding guidelines). +* How to build the project. +* How to run tests to make sure the above modifications aren't introducing new bugs. +* How to submit your modifications back to the project. +* Some information on which turnaround time to expect for modifications made. + + + +### COMMUNICATION.md + +Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. + +Sections in the `COMMUNICATION.md` include points of contact for incoming communications and information about outgoing communications from the project's ownership team. See some examples below. + +Points of contact for incoming communication and how to contact those users: + +* Reporting a bug +* Following up on a PR +* Feature requests +* Questions about documentation +* Escalations + +How and when the team communicates outbound with users and how to get added to those communications: + +* Planned and unplanned outages +* Feature releases +* Code freezes +* Breaking changes + +There are many of good examples for how to write a `README.md` and what kind +of information to include in a `CONTRIBUTING.md` file in various open source projects. +Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), +[Open Source Guide from GitHub](https://opensource.guide/) as well as +the book [Producing Open Source](https://producingoss.com/en/producingoss.html) +all have valuable information on what kind of information to provide. While +Producing Open Source does not have a chapter on writing a good README per se, +the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) +does provide a fairly extensive list of things that fellow host team members, +users and contributors will need. InnerSource projects likely will not cover all +of those aspects right from the start, the list itself is helpful for +inspiration for what one could cover. + +In addition to that, this pattern comes with three very basic templates to get you +started right away: [README-template.md](templates/README-template.md), +[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). + +## Resulting Context + +* The time for contributors to get up to speed is significantly reduced. +* Time spent on answering initial questions for [Trusted Committers](trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. +* Escalations due to misunderstandings and misalignment are significantly reduced. + +## Known Instances + +* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) +* Paypal Inc. +* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). +* Analog Devices Inc. +* Airbus + +## Authors + +* Isabel Drost-Fromm + +## Acknowledgments + +* Katie Schueths - for adding the `COMMUNICATION.md` concept + +## Alias + +Provide standard base documentation through a README + +## Status + +* Structured +* Drafted in December 2019. + +## References + +* [README-template.md](templates/README-template.md) and +* [CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md) + +## Credits + +[Web](https://storyset.com/web) and [People](https://storyset.com/people) illustrations by Storyset ```

30 Day Warranty (patterns/2-structured/30-day-warranty.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/30-day-warranty.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md # index 7c2ab75..ce93a1b 100644 # --- a/patterns/2-structured/30-day-warranty.md # +++ b/patterns/2-structured/30-day-warranty.md @@ -34,7 +34,7 @@ Address the fears of both the receiving and the contributing teams by establishi Note that the warranty period could be 45, 60, or 100 days too. The duration may vary based upon the constraints of the project, the software life cycle of the project, commitments to customers, and other factors. -In addition it helps to provide clear [contribution guidelines](./project-setup/base-documentation.md), spelling out the expectations of the receiving team and the contributing team. +In addition it helps to provide clear [contribution guidelines](./base-documentation.md), spelling out the expectations of the receiving team and the contributing team.  ```

Maturity Model (patterns/2-structured/maturity-model.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/maturity-model.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/maturity-model.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md # index 8e41062..629c2e4 100644 # --- a/patterns/2-structured/maturity-model.md # +++ b/patterns/2-structured/maturity-model.md @@ -213,6 +213,7 @@ long term. * Entelgy * Zylk * Bitergia +* Airbus ## Authors ```

Repository Activity Score (patterns/2-structured/repository-activity-score.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/repository-activity-score.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/repository-activity-score.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md # index 27421a6..dae8f3e 100644 # --- a/patterns/2-structured/repository-activity-score.md # +++ b/patterns/2-structured/repository-activity-score.md @@ -115,7 +115,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances * Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). -* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./project-setup/base-documentation.md) and the [InnerSource License](./innersource-license.md). +* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./base-documentation.md) and the [InnerSource License](./innersource-license.md). ## Status ```

InnerSource License (patterns/2-structured/innersource-license.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-license.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/innersource-license.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...5e711f0133f5f58ab98e4c03b0475c63036e37c8) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md # index 54b5c55..169ea8a 100644 # --- a/patterns/2-structured/innersource-license.md # +++ b/patterns/2-structured/innersource-license.md @@ -32,6 +32,7 @@ At the time of sharing the source code, it can not be reliably predicted what th - Freedom over using the software leads to competition, and spread of ownership - There are legal contracts in place which cover the sharing of source code. These contracts are not standardized, so they create additional effort in negotiating and understanding for every project. The existing contracts may also not allow sharing source code in an open enough sense to support a true InnerSource approach. - Alternatively, there are no legal contracts in place but source code is shared informally. That might create uncertainty in cases where clarity about ownership and rights and obligations is needed. +- Choosing a restrictive and/or copyleft license can constitute a barrier for InnerSource adoption. Specifically, limiting publication to the organisation might require a costly relicensing procedure prior to transitioning to Open Source. ## Solutions @@ -51,6 +52,12 @@ The license simplifies the conversations within our organization about sharing s ## Known Instances +- **DB Systel** +- **Robert Bosch GmbH** +- **Airbus** + +## DB Systel + DB Systel created their own InnerSource License, see [DB Inner Source License][db-inner-source-license]. They used the [EUPL][eupl], as that offered an open source like starting point, and then worked out the constraints and additional rules required in their specific organizational context. The first legal entities (companies) within the DB AG are using their InnerSource License. @@ -66,6 +73,8 @@ The mentioned collaboration challenges include: It is worth mentioning that so far the software shared under this InnerSource license is mostly tooling, infrastructure, and tools lower in the stack. +## Airbus + Airbus created ad hoc InnerSource licenses to enable InnerSource way of working within a large part of the group. ## Status ```

Issue Tracker Use Cases (patterns/2-structured/issue-tracker.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/issue-tracker.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/issue-tracker.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/issue-tracker.md b/patterns/2-structured/issue-tracker.md # new file mode 100644 # index 0000000..ffbda05 # --- /dev/null +++ b/patterns/2-structured/issue-tracker.md @@ -0,0 +1,60 @@ +## Title + +Issue Tracker Use Cases + +## Patlet + +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. + +## Problem + +A team develops a component that many teams in the organization depend on. It +uses a standard issue tracker for tracking open bugs and feature requests. +However, the context in each entry is very limited. As a result potential +contributors have no way of knowing what change exactly each issue is talking +about. + +## Context + +The InnerSource project tooling is all setup. However, the project issue tracker +is mainly used for sharing progress. In InnerSource projects there are many more +use cases that an issue tracker can be used for that make remote, asynchronous +communication easier. + +## Forces + +- Contributors would like to understand whether the feature that they are missing is already on the roadmap. With a lot of context missing in issues though it is impossible to decide whether existing issues match the contributing team's needs. +- As a result a lot of duplicate issues are being opened that the host team has to deal with. +- As context in open issues is so limited contributors are unable to help the host team by implementing some easier issues that are open already. As a result a lot of work remains in the hands of the host team. +- With a strong focus on verbal communication it is impossible to discern after a couple months or years why a certain feature was being chosen for implementation. As a result refactorings, in particular simplifying the component becomes an exercise in project archaeology and brain picking of people who remember what was discussed. + +## Solution + +Embrace the "written over verbal" philosophy not only for pure software +development but also during the planning phase of new features: + +- For bugs, planned features and feature ideas create separate issues. In each of those include as much information as possible so that potential external contributors are able to understand the context. Ideally, in particular for easier changes, include enough information for external contributors to support the host team by implementing the functionality in question. +- Potentially use the issue tracker as a channel to ask questions. This is in particular helpful if you are lacking other communication sources to tackle user questions. +- Make use of tags and categories in order to distinguish issues used for different purposes. +- For starting a brainstorming session asynchronously, open an issue for gathering ideas. When discussion is starting to calm down, summarize the points identified in this issue in a separate document. Post that for review as a pull request to drill deeper into individual points that still need clarification. The resulting document can be used to publish the results in other appropriate channels as well as for future reference. +- Most issue tracker implementations allow for issue templates. Make use of those not only to collect commonly needed information for bug reports but also include hints about what kind of information is needed for the other usage types. + +## Resulting Context + +- Making more use of the project's issue tracker for communication enables external contributors to follow along and make better decisions on what to contribute. +- A focus on structured written communication enables host team members to participate remotely. +- Consistently communicating in writing means that passive documentation on project decisions accumulates as a by-product instead of needing added attention. +- Consistently using public communication channels leads to more humans following a discussion. This means that there are more knowledgeable humans that can answer questions, chime in on open issues, or point out flaws in planned features that would otherwise be found only much later. +- Moving discussions to a public discussion medium creates an opportunity for potential future contributors to lurk, follow along, get comfortable and learn the ways of the project long before they have the first need to get involved. + +## Known Instances + +* Europace AG - See blog post [Issue Use Cases](https://tech.europace.de/post/using-issues-for-asking-questions-and-tracking-work/) + +## Authors + +Isabel Drost-Fromm + +## Status + +Structured ```

Dedicated Community Leader (patterns/2-structured/dedicated-community-leader.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/dedicated-community-leader.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/dedicated-community-leader.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md # index 91f3c3d..8f5235d 100644 # --- a/patterns/2-structured/dedicated-community-leader.md # +++ b/patterns/2-structured/dedicated-community-leader.md @@ -59,6 +59,7 @@ Having excellent and dedicated community leaders is a precondition for the succe ## Known Instances * _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. +* _Airbus_. A data scientist wanted to improve the collaboration with peers in the group and found: i) many developers (beyond data science) wanted that too and were happy someone was taking care of the issue, and ii) support from line manager and middle management to eventually act as the _de facto_ community leader, on top of his regular line of duty. ## Alias ```

Start as an Experiment (patterns/2-structured/start-as-experiment.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/start-as-experiment.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/start-as-experiment.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md # index 53326df..56e0c7d 100644 # --- a/patterns/2-structured/start-as-experiment.md # +++ b/patterns/2-structured/start-as-experiment.md @@ -54,6 +54,7 @@ Finally, starting as an experiment makes it much easier to sidestep regulations ## Known Instances - Robert Bosch GmbH (globally distributed software development) +- Airbus: the data science community collaborated on shared Python libraries that eventually lead to a group-wide InnerSource scheme for any software. ## Status ```

[github-actions[bot]]

i18n Contents Consistency Issue

The following files may have consistency issues with the English version. Please check and update the files.

This issue is created when any of the English patterns have changed (in folder ). It compares the git update history to let you know what updates are overdue. The issue should be closed when the update is complete.

Communication Tooling (patterns/2-structured/communication-tooling.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/communication-tooling.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/communication-tooling.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/communication-tooling.md b/patterns/2-structured/communication-tooling.md # new file mode 100644 # index 0000000..08b1a33 # --- /dev/null +++ b/patterns/2-structured/communication-tooling.md @@ -0,0 +1,96 @@ +## Title + +Communication Tooling + +## Patlet + +The users of an InnerSource project have trouble getting help and getting in touch with the host team. +By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. + +## Problem + +A team is open to receiving contributions from downstream users of their +component. Coordination and communication happens in an ad hoc fashion though +leading to incoherent information being shared, delays in answers received, +contributors pinging multiple host team members before receiving a definitive +answer. + +## Context + +- A team depends on another team's component. +- It would like to make contributions to that component. +- Even when it happens in writing, communication happens in a 1-on-1 fashion. + +## Forces + +- The host team is interested in receiving contributions and willing to mentor contributors. +- Teams have a strong verbal communication culture and are inexperienced with setting up project specific asynchronous communication channels. +- Communication channels may be aligned with specific groups that should be reached but not by communication purpose. + +## Solution + +The host team should provide company-public, archived, searchable, linkable communication channels that anyone in the company can subscribe to, as there are measurable benefits to supporting open, written communications channels. + +The goal when streamlining communication channels for InnerSource projects +should be to align communication around topics, not around certain sets of +people. + +A project should set up the following communication tooling: + +1. **a dedicated issue tracker** where structured communication, decision-making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow. For further applications of the issue tracker see [Issue Tracker Use Cases](./issue-tracker.md). +2. **public discussion channel(s)** that come with less rigid a structure. Typically, this will be mailing lists, online forums, Q&A systems or even archived chat channels. Usually it is enough to start with just one channel for the project. If traffic increases too much it is helpful to split discussions about project usage from discussions about project development. +3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](./trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. + +While communication can happen outside of those written channels, as much information as possible should be brought back to the asynchronous channels. + +All communication channels should be documented in the project `README.md`. For more details on the use of this file see [Standard Base Documentation](./base-documentation.md). + +The host team members need to make an effort to direct questions that they receive personally (e.g. via email or private chat messages) back to official communication channels. + + + +## Resulting Context + +Setting up and consistently using official asynchronous communication channels +helps create a base level of [passive documentation](https://www.oreilly.com/library/view/understanding-the-innersource/9781491986899/ch04.html) that can be referenced again when similar questions come up again. + +With communication happening in the open others can easily follow project +progress and get active contributing. Others lurking and reading lowers the +barrier to get involved raising the likelihood of receiving contributions. + +With questions being answered in public more people can add their perspective +leading to a complete picture - this includes not only host team members, +but also users of the project. + +Keeping communication in asynchronous channels allows for participants on +different schedules - either due to different time zones or due to different +routines, meeting schedules, team routines - to meaningfully contribute to +the project. + +Answering questions in those channels means that not only other team members +can listen in and provide additional information, it also means that other +users with the same question see (or later find) the previous answer leading +to a lower need to repeat explanations. + +## Known Instances + +* Europace AG +* Paypal Inc. +* Mercado Libre + +## Authors + +Isabel Drost-Fromm + +## Acknowledgment + +Sebastian Spier (for the visual) + +## Status + +* Structured +* Drafted in December 2019. + +## Credits + +[People](https://storyset.com/people) illustrations by Storyset ```

Standard Base Documentation (patterns/2-structured/base-documentation.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/base-documentation.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/base-documentation.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md # new file mode 100644 # index 0000000..bd20b82 # --- /dev/null +++ b/patterns/2-structured/base-documentation.md @@ -0,0 +1,161 @@ +## Title + +Standard Base Documentation + +## Patlet + +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`/`COMMUNICATION.md` enables a +self service process for new contributors, so that they can find the answers to +the most common questions on their own. + +## Problem + +A team wants to share either a freshly started or a preexisting project with +the wider organization and receive contributions to it. Potential contributors +often are lost: They are failing to identify the team's preferred communication +channels. They have trouble quickly making a judgment about whether a new +feature makes sense to be added or not. They have a hard time understanding +exactly which colleagues are currently actively maintaining the project. + +## Context + +A project is to be shared with others as an InnerSource project. In order for +others to be able to understand what the project is about as well as how to +contribute, the project needs to provide some base level documentation. So far +the project is lacking either all documentation or some aspects needed for users +to try it out in a self-service manner as well as for contributors to get up to +speed quickly. + +## Forces + +- The project was converted into an InnerSource project only recently. Before, users were either only internal or on-boarded in personal face-to-face sessions. Equally, people working on the project went through personal on-boarding sessions which do not scale with growing numbers of contributors or remote contributors. As a result, self service documentation is lacking. +- The project was newly created as an InnerSource project. However the host team lacks experience with InnerSource. As a result they need guidance on which information to include in their documentation, where to put that documentation so others can find it and which types of readers to address in their documentation. +- The project was converted into an InnerSource project only recently, the host team has limited experience with InnerSource. As a result, existing documentation addresses a lot of technical aspects. It does not cover communication, coordination, information needed to facilitate transparent planning. +- The project was converted into an InnerSource project only recently. As a result, a lot of implicit knowledge that exists within the team is neither written down nor obvious to contributors. +- A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing documentation (and keeping it up to date) requires a time investment. Even if the host team relies on contributors to help with lacking documentation, those contributions still need time to review. +- Project members are spending a lot of time answering getting started questions. Maintaining a comprehensive database of what could be considered support questions requires a lot of time and effort though. +- Different teams within the organization have diverging standards for how to format source code and which software patterns to use. As a result contributions often end up getting re-written to a large part or even entirely. Standardizing all of that and enforcing the standard often would require a lot of time and work. +- The added work for repeated explanations and re-writes diminishes the usefulness of the InnerSource approach. +- Frequent escalations due to extra work and delays due to re-writes lead to a big cheese situation. + +## Solution + +Address the need for clearer documentation for new contributors. The goal when +creating this documentation should be to make getting started as much a self +service process as possible with frequently asked questions answered in standard +documentation format. + +### README.md + +If it does not yet exist, create a `README.md` for your project. It should +contain: + +* The [mission of the project](https://producingoss.com/en/producingoss.html#mission-statement) in as a concise format as possible. It should answer what the project's purpose is and enable contributors to make a good first guess whether a suggested feature will likely be in scope for the project, or not. +* A "Getting Started" section for downstream users of the project. It should explain how to setup/ integrate the project artifacts as well as an explanation of some of the first typical steps for first time users. +* Deeper documentation for project users - or a link to that. +* Documentation needed for making modifications to the project - or a link to that. +* Documentation on how to contribute to the project - or a link to that. +* A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used. +* A "Who we are" section explaining who the [Trusted Committers](trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. +* An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists. + + + +### CONTRIBUTING.md + +If the explanation of the steps to make a contribution are too involved, create +a separate `CONTRIBUTING.md` document. This document should answer frequently +asked questions that contributors have asked in the past. There is no need to +provide a comprehensive book up front. Rather, share information that has proven +needed by contributors. Likely it will touch upon one or more of the following +topics: + +* How to checkout the project source code from version control. +* How to make modifications to the project (potentially including information on coding guidelines). +* How to build the project. +* How to run tests to make sure the above modifications aren't introducing new bugs. +* How to submit your modifications back to the project. +* Some information on which turnaround time to expect for modifications made. + + + +### COMMUNICATION.md + +Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. + +Sections in the `COMMUNICATION.md` include points of contact for incoming communications and information about outgoing communications from the project's ownership team. See some examples below. + +Points of contact for incoming communication and how to contact those users: + +* Reporting a bug +* Following up on a PR +* Feature requests +* Questions about documentation +* Escalations + +How and when the team communicates outbound with users and how to get added to those communications: + +* Planned and unplanned outages +* Feature releases +* Code freezes +* Breaking changes + +There are many of good examples for how to write a `README.md` and what kind +of information to include in a `CONTRIBUTING.md` file in various open source projects. +Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), +[Open Source Guide from GitHub](https://opensource.guide/) as well as +the book [Producing Open Source](https://producingoss.com/en/producingoss.html) +all have valuable information on what kind of information to provide. While +Producing Open Source does not have a chapter on writing a good README per se, +the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) +does provide a fairly extensive list of things that fellow host team members, +users and contributors will need. InnerSource projects likely will not cover all +of those aspects right from the start, the list itself is helpful for +inspiration for what one could cover. + +In addition to that, this pattern comes with three very basic templates to get you +started right away: [README-template.md](templates/README-template.md), +[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). + +## Resulting Context + +* The time for contributors to get up to speed is significantly reduced. +* Time spent on answering initial questions for [Trusted Committers](trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. +* Escalations due to misunderstandings and misalignment are significantly reduced. + +## Known Instances + +* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) +* Paypal Inc. +* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). +* Analog Devices Inc. +* Airbus + +## Authors + +* Isabel Drost-Fromm + +## Acknowledgments + +* Katie Schueths - for adding the `COMMUNICATION.md` concept + +## Alias + +Provide standard base documentation through a README + +## Status + +* Structured +* Drafted in December 2019. + +## References + +* [README-template.md](templates/README-template.md) and +* [CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md) + +## Credits + +[Web](https://storyset.com/web) and [People](https://storyset.com/people) illustrations by Storyset ```

30 Day Warranty (patterns/2-structured/30-day-warranty.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/30-day-warranty.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md # index 7c2ab75..ce93a1b 100644 # --- a/patterns/2-structured/30-day-warranty.md # +++ b/patterns/2-structured/30-day-warranty.md @@ -34,7 +34,7 @@ Address the fears of both the receiving and the contributing teams by establishi Note that the warranty period could be 45, 60, or 100 days too. The duration may vary based upon the constraints of the project, the software life cycle of the project, commitments to customers, and other factors. -In addition it helps to provide clear [contribution guidelines](./project-setup/base-documentation.md), spelling out the expectations of the receiving team and the contributing team. +In addition it helps to provide clear [contribution guidelines](./base-documentation.md), spelling out the expectations of the receiving team and the contributing team.  ```

Maturity Model (patterns/2-structured/maturity-model.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/maturity-model.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/maturity-model.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md # index 8e41062..629c2e4 100644 # --- a/patterns/2-structured/maturity-model.md # +++ b/patterns/2-structured/maturity-model.md @@ -213,6 +213,7 @@ long term. * Entelgy * Zylk * Bitergia +* Airbus ## Authors ```

Repository Activity Score (patterns/2-structured/repository-activity-score.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/repository-activity-score.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/repository-activity-score.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md # index 27421a6..dae8f3e 100644 # --- a/patterns/2-structured/repository-activity-score.md # +++ b/patterns/2-structured/repository-activity-score.md @@ -115,7 +115,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances * Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). -* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./project-setup/base-documentation.md) and the [InnerSource License](./innersource-license.md). +* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./base-documentation.md) and the [InnerSource License](./innersource-license.md). ## Status ```

InnerSource License (patterns/2-structured/innersource-license.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-license.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/innersource-license.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...5e711f0133f5f58ab98e4c03b0475c63036e37c8) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md # index 54b5c55..169ea8a 100644 # --- a/patterns/2-structured/innersource-license.md # +++ b/patterns/2-structured/innersource-license.md @@ -32,6 +32,7 @@ At the time of sharing the source code, it can not be reliably predicted what th - Freedom over using the software leads to competition, and spread of ownership - There are legal contracts in place which cover the sharing of source code. These contracts are not standardized, so they create additional effort in negotiating and understanding for every project. The existing contracts may also not allow sharing source code in an open enough sense to support a true InnerSource approach. - Alternatively, there are no legal contracts in place but source code is shared informally. That might create uncertainty in cases where clarity about ownership and rights and obligations is needed. +- Choosing a restrictive and/or copyleft license can constitute a barrier for InnerSource adoption. Specifically, limiting publication to the organisation might require a costly relicensing procedure prior to transitioning to Open Source. ## Solutions @@ -51,6 +52,12 @@ The license simplifies the conversations within our organization about sharing s ## Known Instances +- **DB Systel** +- **Robert Bosch GmbH** +- **Airbus** + +## DB Systel + DB Systel created their own InnerSource License, see [DB Inner Source License][db-inner-source-license]. They used the [EUPL][eupl], as that offered an open source like starting point, and then worked out the constraints and additional rules required in their specific organizational context. The first legal entities (companies) within the DB AG are using their InnerSource License. @@ -66,6 +73,8 @@ The mentioned collaboration challenges include: It is worth mentioning that so far the software shared under this InnerSource license is mostly tooling, infrastructure, and tools lower in the stack. +## Airbus + Airbus created ad hoc InnerSource licenses to enable InnerSource way of working within a large part of the group. ## Status ```

Issue Tracker Use Cases (patterns/2-structured/issue-tracker.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/issue-tracker.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/issue-tracker.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **4** days. ```diff # diff --git a/patterns/2-structured/issue-tracker.md b/patterns/2-structured/issue-tracker.md # new file mode 100644 # index 0000000..ffbda05 # --- /dev/null +++ b/patterns/2-structured/issue-tracker.md @@ -0,0 +1,60 @@ +## Title + +Issue Tracker Use Cases + +## Patlet + +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. + +## Problem + +A team develops a component that many teams in the organization depend on. It +uses a standard issue tracker for tracking open bugs and feature requests. +However, the context in each entry is very limited. As a result potential +contributors have no way of knowing what change exactly each issue is talking +about. + +## Context + +The InnerSource project tooling is all setup. However, the project issue tracker +is mainly used for sharing progress. In InnerSource projects there are many more +use cases that an issue tracker can be used for that make remote, asynchronous +communication easier. + +## Forces + +- Contributors would like to understand whether the feature that they are missing is already on the roadmap. With a lot of context missing in issues though it is impossible to decide whether existing issues match the contributing team's needs. +- As a result a lot of duplicate issues are being opened that the host team has to deal with. +- As context in open issues is so limited contributors are unable to help the host team by implementing some easier issues that are open already. As a result a lot of work remains in the hands of the host team. +- With a strong focus on verbal communication it is impossible to discern after a couple months or years why a certain feature was being chosen for implementation. As a result refactorings, in particular simplifying the component becomes an exercise in project archaeology and brain picking of people who remember what was discussed. + +## Solution + +Embrace the "written over verbal" philosophy not only for pure software +development but also during the planning phase of new features: + +- For bugs, planned features and feature ideas create separate issues. In each of those include as much information as possible so that potential external contributors are able to understand the context. Ideally, in particular for easier changes, include enough information for external contributors to support the host team by implementing the functionality in question. +- Potentially use the issue tracker as a channel to ask questions. This is in particular helpful if you are lacking other communication sources to tackle user questions. +- Make use of tags and categories in order to distinguish issues used for different purposes. +- For starting a brainstorming session asynchronously, open an issue for gathering ideas. When discussion is starting to calm down, summarize the points identified in this issue in a separate document. Post that for review as a pull request to drill deeper into individual points that still need clarification. The resulting document can be used to publish the results in other appropriate channels as well as for future reference. +- Most issue tracker implementations allow for issue templates. Make use of those not only to collect commonly needed information for bug reports but also include hints about what kind of information is needed for the other usage types. + +## Resulting Context + +- Making more use of the project's issue tracker for communication enables external contributors to follow along and make better decisions on what to contribute. +- A focus on structured written communication enables host team members to participate remotely. +- Consistently communicating in writing means that passive documentation on project decisions accumulates as a by-product instead of needing added attention. +- Consistently using public communication channels leads to more humans following a discussion. This means that there are more knowledgeable humans that can answer questions, chime in on open issues, or point out flaws in planned features that would otherwise be found only much later. +- Moving discussions to a public discussion medium creates an opportunity for potential future contributors to lurk, follow along, get comfortable and learn the ways of the project long before they have the first need to get involved. + +## Known Instances + +* Europace AG - See blog post [Issue Use Cases](https://tech.europace.de/post/using-issues-for-asking-questions-and-tracking-work/) + +## Authors + +Isabel Drost-Fromm + +## Status + +Structured ```

Dedicated Community Leader (patterns/2-structured/dedicated-community-leader.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/dedicated-community-leader.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/dedicated-community-leader.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md # index 91f3c3d..8f5235d 100644 # --- a/patterns/2-structured/dedicated-community-leader.md # +++ b/patterns/2-structured/dedicated-community-leader.md @@ -59,6 +59,7 @@ Having excellent and dedicated community leaders is a precondition for the succe ## Known Instances * _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. +* _Airbus_. A data scientist wanted to improve the collaboration with peers in the group and found: i) many developers (beyond data science) wanted that too and were happy someone was taking care of the issue, and ii) support from line manager and middle management to eventually act as the _de facto_ community leader, on top of his regular line of duty. ## Alias ```

Start as an Experiment (patterns/2-structured/start-as-experiment.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/start-as-experiment.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/start-as-experiment.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **11** days. ```diff # diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md # index 53326df..56e0c7d 100644 # --- a/patterns/2-structured/start-as-experiment.md # +++ b/patterns/2-structured/start-as-experiment.md @@ -54,6 +54,7 @@ Finally, starting as an experiment makes it much easier to sidestep regulations ## Known Instances - Robert Bosch GmbH (globally distributed software development) +- Airbus: the data science community collaborated on shared Python libraries that eventually lead to a group-wide InnerSource scheme for any software. ## Status ```

[github-actions[bot]]

i18n Contents Consistency Issue

The following files may have consistency issues with the English version. Please check and update the files.

This issue is created when any of the English patterns have changed (in folder ). It compares the git update history to let you know what updates are overdue. The issue should be closed when the update is complete.

30 Day Warranty (patterns/2-structured/30-day-warranty.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/30-day-warranty.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **29** days. ```diff # diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md # index 7c2ab75..ce93a1b 100644 # --- a/patterns/2-structured/30-day-warranty.md # +++ b/patterns/2-structured/30-day-warranty.md @@ -34,7 +34,7 @@ Address the fears of both the receiving and the contributing teams by establishi Note that the warranty period could be 45, 60, or 100 days too. The duration may vary based upon the constraints of the project, the software life cycle of the project, commitments to customers, and other factors. -In addition it helps to provide clear [contribution guidelines](./project-setup/base-documentation.md), spelling out the expectations of the receiving team and the contributing team. +In addition it helps to provide clear [contribution guidelines](./base-documentation.md), spelling out the expectations of the receiving team and the contributing team.  ```

Communication Tooling (patterns/2-structured/communication-tooling.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/communication-tooling.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/communication-tooling.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **29** days. ```diff # diff --git a/patterns/2-structured/communication-tooling.md b/patterns/2-structured/communication-tooling.md # new file mode 100644 # index 0000000..08b1a33 # --- /dev/null +++ b/patterns/2-structured/communication-tooling.md @@ -0,0 +1,96 @@ +## Title + +Communication Tooling + +## Patlet + +The users of an InnerSource project have trouble getting help and getting in touch with the host team. +By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. + +## Problem + +A team is open to receiving contributions from downstream users of their +component. Coordination and communication happens in an ad hoc fashion though +leading to incoherent information being shared, delays in answers received, +contributors pinging multiple host team members before receiving a definitive +answer. + +## Context + +- A team depends on another team's component. +- It would like to make contributions to that component. +- Even when it happens in writing, communication happens in a 1-on-1 fashion. + +## Forces + +- The host team is interested in receiving contributions and willing to mentor contributors. +- Teams have a strong verbal communication culture and are inexperienced with setting up project specific asynchronous communication channels. +- Communication channels may be aligned with specific groups that should be reached but not by communication purpose. + +## Solution + +The host team should provide company-public, archived, searchable, linkable communication channels that anyone in the company can subscribe to, as there are measurable benefits to supporting open, written communications channels. + +The goal when streamlining communication channels for InnerSource projects +should be to align communication around topics, not around certain sets of +people. + +A project should set up the following communication tooling: + +1. **a dedicated issue tracker** where structured communication, decision-making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow. For further applications of the issue tracker see [Issue Tracker Use Cases](./issue-tracker.md). +2. **public discussion channel(s)** that come with less rigid a structure. Typically, this will be mailing lists, online forums, Q&A systems or even archived chat channels. Usually it is enough to start with just one channel for the project. If traffic increases too much it is helpful to split discussions about project usage from discussions about project development. +3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](./trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. + +While communication can happen outside of those written channels, as much information as possible should be brought back to the asynchronous channels. + +All communication channels should be documented in the project `README.md`. For more details on the use of this file see [Standard Base Documentation](./base-documentation.md). + +The host team members need to make an effort to direct questions that they receive personally (e.g. via email or private chat messages) back to official communication channels. + + + +## Resulting Context + +Setting up and consistently using official asynchronous communication channels +helps create a base level of [passive documentation](https://www.oreilly.com/library/view/understanding-the-innersource/9781491986899/ch04.html) that can be referenced again when similar questions come up again. + +With communication happening in the open others can easily follow project +progress and get active contributing. Others lurking and reading lowers the +barrier to get involved raising the likelihood of receiving contributions. + +With questions being answered in public more people can add their perspective +leading to a complete picture - this includes not only host team members, +but also users of the project. + +Keeping communication in asynchronous channels allows for participants on +different schedules - either due to different time zones or due to different +routines, meeting schedules, team routines - to meaningfully contribute to +the project. + +Answering questions in those channels means that not only other team members +can listen in and provide additional information, it also means that other +users with the same question see (or later find) the previous answer leading +to a lower need to repeat explanations. + +## Known Instances + +* Europace AG +* Paypal Inc. +* Mercado Libre + +## Authors + +Isabel Drost-Fromm + +## Acknowledgment + +Sebastian Spier (for the visual) + +## Status + +* Structured +* Drafted in December 2019. + +## Credits + +[People](https://storyset.com/people) illustrations by Storyset ```

Dedicated Community Leader (patterns/2-structured/dedicated-community-leader.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/dedicated-community-leader.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/dedicated-community-leader.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **37** days. ```diff # diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md # index 91f3c3d..8f5235d 100644 # --- a/patterns/2-structured/dedicated-community-leader.md # +++ b/patterns/2-structured/dedicated-community-leader.md @@ -59,6 +59,7 @@ Having excellent and dedicated community leaders is a precondition for the succe ## Known Instances * _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. +* _Airbus_. A data scientist wanted to improve the collaboration with peers in the group and found: i) many developers (beyond data science) wanted that too and were happy someone was taking care of the issue, and ii) support from line manager and middle management to eventually act as the _de facto_ community leader, on top of his regular line of duty. ## Alias ```

Maturity Model (patterns/2-structured/maturity-model.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/maturity-model.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/maturity-model.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **37** days. ```diff # diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md # index 8e41062..629c2e4 100644 # --- a/patterns/2-structured/maturity-model.md # +++ b/patterns/2-structured/maturity-model.md @@ -213,6 +213,7 @@ long term. * Entelgy * Zylk * Bitergia +* Airbus ## Authors ```

Issue Tracker Use Cases (patterns/2-structured/issue-tracker.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/issue-tracker.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/issue-tracker.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **29** days. ```diff # diff --git a/patterns/2-structured/issue-tracker.md b/patterns/2-structured/issue-tracker.md # new file mode 100644 # index 0000000..ffbda05 # --- /dev/null +++ b/patterns/2-structured/issue-tracker.md @@ -0,0 +1,60 @@ +## Title + +Issue Tracker Use Cases + +## Patlet + +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. + +## Problem + +A team develops a component that many teams in the organization depend on. It +uses a standard issue tracker for tracking open bugs and feature requests. +However, the context in each entry is very limited. As a result potential +contributors have no way of knowing what change exactly each issue is talking +about. + +## Context + +The InnerSource project tooling is all setup. However, the project issue tracker +is mainly used for sharing progress. In InnerSource projects there are many more +use cases that an issue tracker can be used for that make remote, asynchronous +communication easier. + +## Forces + +- Contributors would like to understand whether the feature that they are missing is already on the roadmap. With a lot of context missing in issues though it is impossible to decide whether existing issues match the contributing team's needs. +- As a result a lot of duplicate issues are being opened that the host team has to deal with. +- As context in open issues is so limited contributors are unable to help the host team by implementing some easier issues that are open already. As a result a lot of work remains in the hands of the host team. +- With a strong focus on verbal communication it is impossible to discern after a couple months or years why a certain feature was being chosen for implementation. As a result refactorings, in particular simplifying the component becomes an exercise in project archaeology and brain picking of people who remember what was discussed. + +## Solution + +Embrace the "written over verbal" philosophy not only for pure software +development but also during the planning phase of new features: + +- For bugs, planned features and feature ideas create separate issues. In each of those include as much information as possible so that potential external contributors are able to understand the context. Ideally, in particular for easier changes, include enough information for external contributors to support the host team by implementing the functionality in question. +- Potentially use the issue tracker as a channel to ask questions. This is in particular helpful if you are lacking other communication sources to tackle user questions. +- Make use of tags and categories in order to distinguish issues used for different purposes. +- For starting a brainstorming session asynchronously, open an issue for gathering ideas. When discussion is starting to calm down, summarize the points identified in this issue in a separate document. Post that for review as a pull request to drill deeper into individual points that still need clarification. The resulting document can be used to publish the results in other appropriate channels as well as for future reference. +- Most issue tracker implementations allow for issue templates. Make use of those not only to collect commonly needed information for bug reports but also include hints about what kind of information is needed for the other usage types. + +## Resulting Context + +- Making more use of the project's issue tracker for communication enables external contributors to follow along and make better decisions on what to contribute. +- A focus on structured written communication enables host team members to participate remotely. +- Consistently communicating in writing means that passive documentation on project decisions accumulates as a by-product instead of needing added attention. +- Consistently using public communication channels leads to more humans following a discussion. This means that there are more knowledgeable humans that can answer questions, chime in on open issues, or point out flaws in planned features that would otherwise be found only much later. +- Moving discussions to a public discussion medium creates an opportunity for potential future contributors to lurk, follow along, get comfortable and learn the ways of the project long before they have the first need to get involved. + +## Known Instances + +* Europace AG - See blog post [Issue Use Cases](https://tech.europace.de/post/using-issues-for-asking-questions-and-tracking-work/) + +## Authors + +Isabel Drost-Fromm + +## Status + +Structured ```

Repository Activity Score (patterns/2-structured/repository-activity-score.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/repository-activity-score.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/repository-activity-score.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **29** days. ```diff # diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md # index 27421a6..dae8f3e 100644 # --- a/patterns/2-structured/repository-activity-score.md # +++ b/patterns/2-structured/repository-activity-score.md @@ -115,7 +115,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances * Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). -* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./project-setup/base-documentation.md) and the [InnerSource License](./innersource-license.md). +* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./base-documentation.md) and the [InnerSource License](./innersource-license.md). ## Status ```

Standard Base Documentation (patterns/2-structured/base-documentation.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/base-documentation.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/base-documentation.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **29** days. ```diff # diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md # new file mode 100644 # index 0000000..bd20b82 # --- /dev/null +++ b/patterns/2-structured/base-documentation.md @@ -0,0 +1,161 @@ +## Title + +Standard Base Documentation + +## Patlet + +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`/`COMMUNICATION.md` enables a +self service process for new contributors, so that they can find the answers to +the most common questions on their own. + +## Problem + +A team wants to share either a freshly started or a preexisting project with +the wider organization and receive contributions to it. Potential contributors +often are lost: They are failing to identify the team's preferred communication +channels. They have trouble quickly making a judgment about whether a new +feature makes sense to be added or not. They have a hard time understanding +exactly which colleagues are currently actively maintaining the project. + +## Context + +A project is to be shared with others as an InnerSource project. In order for +others to be able to understand what the project is about as well as how to +contribute, the project needs to provide some base level documentation. So far +the project is lacking either all documentation or some aspects needed for users +to try it out in a self-service manner as well as for contributors to get up to +speed quickly. + +## Forces + +- The project was converted into an InnerSource project only recently. Before, users were either only internal or on-boarded in personal face-to-face sessions. Equally, people working on the project went through personal on-boarding sessions which do not scale with growing numbers of contributors or remote contributors. As a result, self service documentation is lacking. +- The project was newly created as an InnerSource project. However the host team lacks experience with InnerSource. As a result they need guidance on which information to include in their documentation, where to put that documentation so others can find it and which types of readers to address in their documentation. +- The project was converted into an InnerSource project only recently, the host team has limited experience with InnerSource. As a result, existing documentation addresses a lot of technical aspects. It does not cover communication, coordination, information needed to facilitate transparent planning. +- The project was converted into an InnerSource project only recently. As a result, a lot of implicit knowledge that exists within the team is neither written down nor obvious to contributors. +- A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing documentation (and keeping it up to date) requires a time investment. Even if the host team relies on contributors to help with lacking documentation, those contributions still need time to review. +- Project members are spending a lot of time answering getting started questions. Maintaining a comprehensive database of what could be considered support questions requires a lot of time and effort though. +- Different teams within the organization have diverging standards for how to format source code and which software patterns to use. As a result contributions often end up getting re-written to a large part or even entirely. Standardizing all of that and enforcing the standard often would require a lot of time and work. +- The added work for repeated explanations and re-writes diminishes the usefulness of the InnerSource approach. +- Frequent escalations due to extra work and delays due to re-writes lead to a big cheese situation. + +## Solution + +Address the need for clearer documentation for new contributors. The goal when +creating this documentation should be to make getting started as much a self +service process as possible with frequently asked questions answered in standard +documentation format. + +### README.md + +If it does not yet exist, create a `README.md` for your project. It should +contain: + +* The [mission of the project](https://producingoss.com/en/producingoss.html#mission-statement) in as a concise format as possible. It should answer what the project's purpose is and enable contributors to make a good first guess whether a suggested feature will likely be in scope for the project, or not. +* A "Getting Started" section for downstream users of the project. It should explain how to setup/ integrate the project artifacts as well as an explanation of some of the first typical steps for first time users. +* Deeper documentation for project users - or a link to that. +* Documentation needed for making modifications to the project - or a link to that. +* Documentation on how to contribute to the project - or a link to that. +* A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used. +* A "Who we are" section explaining who the [Trusted Committers](trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. +* An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists. + + + +### CONTRIBUTING.md + +If the explanation of the steps to make a contribution are too involved, create +a separate `CONTRIBUTING.md` document. This document should answer frequently +asked questions that contributors have asked in the past. There is no need to +provide a comprehensive book up front. Rather, share information that has proven +needed by contributors. Likely it will touch upon one or more of the following +topics: + +* How to checkout the project source code from version control. +* How to make modifications to the project (potentially including information on coding guidelines). +* How to build the project. +* How to run tests to make sure the above modifications aren't introducing new bugs. +* How to submit your modifications back to the project. +* Some information on which turnaround time to expect for modifications made. + + + +### COMMUNICATION.md + +Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. + +Sections in the `COMMUNICATION.md` include points of contact for incoming communications and information about outgoing communications from the project's ownership team. See some examples below. + +Points of contact for incoming communication and how to contact those users: + +* Reporting a bug +* Following up on a PR +* Feature requests +* Questions about documentation +* Escalations + +How and when the team communicates outbound with users and how to get added to those communications: + +* Planned and unplanned outages +* Feature releases +* Code freezes +* Breaking changes + +There are many of good examples for how to write a `README.md` and what kind +of information to include in a `CONTRIBUTING.md` file in various open source projects. +Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), +[Open Source Guide from GitHub](https://opensource.guide/) as well as +the book [Producing Open Source](https://producingoss.com/en/producingoss.html) +all have valuable information on what kind of information to provide. While +Producing Open Source does not have a chapter on writing a good README per se, +the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) +does provide a fairly extensive list of things that fellow host team members, +users and contributors will need. InnerSource projects likely will not cover all +of those aspects right from the start, the list itself is helpful for +inspiration for what one could cover. + +In addition to that, this pattern comes with three very basic templates to get you +started right away: [README-template.md](templates/README-template.md), +[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). + +## Resulting Context + +* The time for contributors to get up to speed is significantly reduced. +* Time spent on answering initial questions for [Trusted Committers](trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. +* Escalations due to misunderstandings and misalignment are significantly reduced. + +## Known Instances + +* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) +* Paypal Inc. +* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). +* Analog Devices Inc. +* Airbus + +## Authors + +* Isabel Drost-Fromm + +## Acknowledgments + +* Katie Schueths - for adding the `COMMUNICATION.md` concept + +## Alias + +Provide standard base documentation through a README + +## Status + +* Structured +* Drafted in December 2019. + +## References + +* [README-template.md](templates/README-template.md) and +* [CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md) + +## Credits + +[Web](https://storyset.com/web) and [People](https://storyset.com/people) illustrations by Storyset ```

InnerSource License (patterns/2-structured/innersource-license.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-license.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/innersource-license.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...5e711f0133f5f58ab98e4c03b0475c63036e37c8) on GitHub. The number of days since overdue updates is **37** days. ```diff # diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md # index 54b5c55..169ea8a 100644 # --- a/patterns/2-structured/innersource-license.md # +++ b/patterns/2-structured/innersource-license.md @@ -32,6 +32,7 @@ At the time of sharing the source code, it can not be reliably predicted what th - Freedom over using the software leads to competition, and spread of ownership - There are legal contracts in place which cover the sharing of source code. These contracts are not standardized, so they create additional effort in negotiating and understanding for every project. The existing contracts may also not allow sharing source code in an open enough sense to support a true InnerSource approach. - Alternatively, there are no legal contracts in place but source code is shared informally. That might create uncertainty in cases where clarity about ownership and rights and obligations is needed. +- Choosing a restrictive and/or copyleft license can constitute a barrier for InnerSource adoption. Specifically, limiting publication to the organisation might require a costly relicensing procedure prior to transitioning to Open Source. ## Solutions @@ -51,6 +52,12 @@ The license simplifies the conversations within our organization about sharing s ## Known Instances +- **DB Systel** +- **Robert Bosch GmbH** +- **Airbus** + +## DB Systel + DB Systel created their own InnerSource License, see [DB Inner Source License][db-inner-source-license]. They used the [EUPL][eupl], as that offered an open source like starting point, and then worked out the constraints and additional rules required in their specific organizational context. The first legal entities (companies) within the DB AG are using their InnerSource License. @@ -66,6 +73,8 @@ The mentioned collaboration challenges include: It is worth mentioning that so far the software shared under this InnerSource license is mostly tooling, infrastructure, and tools lower in the stack. +## Airbus + Airbus created ad hoc InnerSource licenses to enable InnerSource way of working within a large part of the group. ## Status ```

Start as an Experiment (patterns/2-structured/start-as-experiment.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/start-as-experiment.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/start-as-experiment.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **37** days. ```diff # diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md # index 53326df..56e0c7d 100644 # --- a/patterns/2-structured/start-as-experiment.md # +++ b/patterns/2-structured/start-as-experiment.md @@ -54,6 +54,7 @@ Finally, starting as an experiment makes it much easier to sidestep regulations ## Known Instances - Robert Bosch GmbH (globally distributed software development) +- Airbus: the data science community collaborated on shared Python libraries that eventually lead to a group-wide InnerSource scheme for any software. ## Status ```

[github-actions[bot]]

i18n Contents Consistency Issue

The following files may have consistency issues with the English version. Please check and update the files.

This issue is created when any of the English patterns have changed (in folder ). It compares the git update history to let you know what updates are overdue. The issue should be closed when the update is complete.

Standard Base Documentation (patterns/2-structured/base-documentation.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/base-documentation.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/base-documentation.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **60** days. ```diff # diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md # new file mode 100644 # index 0000000..bd20b82 # --- /dev/null +++ b/patterns/2-structured/base-documentation.md @@ -0,0 +1,161 @@ +## Title + +Standard Base Documentation + +## Patlet + +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`/`COMMUNICATION.md` enables a +self service process for new contributors, so that they can find the answers to +the most common questions on their own. + +## Problem + +A team wants to share either a freshly started or a preexisting project with +the wider organization and receive contributions to it. Potential contributors +often are lost: They are failing to identify the team's preferred communication +channels. They have trouble quickly making a judgment about whether a new +feature makes sense to be added or not. They have a hard time understanding +exactly which colleagues are currently actively maintaining the project. + +## Context + +A project is to be shared with others as an InnerSource project. In order for +others to be able to understand what the project is about as well as how to +contribute, the project needs to provide some base level documentation. So far +the project is lacking either all documentation or some aspects needed for users +to try it out in a self-service manner as well as for contributors to get up to +speed quickly. + +## Forces + +- The project was converted into an InnerSource project only recently. Before, users were either only internal or on-boarded in personal face-to-face sessions. Equally, people working on the project went through personal on-boarding sessions which do not scale with growing numbers of contributors or remote contributors. As a result, self service documentation is lacking. +- The project was newly created as an InnerSource project. However the host team lacks experience with InnerSource. As a result they need guidance on which information to include in their documentation, where to put that documentation so others can find it and which types of readers to address in their documentation. +- The project was converted into an InnerSource project only recently, the host team has limited experience with InnerSource. As a result, existing documentation addresses a lot of technical aspects. It does not cover communication, coordination, information needed to facilitate transparent planning. +- The project was converted into an InnerSource project only recently. As a result, a lot of implicit knowledge that exists within the team is neither written down nor obvious to contributors. +- A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing documentation (and keeping it up to date) requires a time investment. Even if the host team relies on contributors to help with lacking documentation, those contributions still need time to review. +- Project members are spending a lot of time answering getting started questions. Maintaining a comprehensive database of what could be considered support questions requires a lot of time and effort though. +- Different teams within the organization have diverging standards for how to format source code and which software patterns to use. As a result contributions often end up getting re-written to a large part or even entirely. Standardizing all of that and enforcing the standard often would require a lot of time and work. +- The added work for repeated explanations and re-writes diminishes the usefulness of the InnerSource approach. +- Frequent escalations due to extra work and delays due to re-writes lead to a big cheese situation. + +## Solution + +Address the need for clearer documentation for new contributors. The goal when +creating this documentation should be to make getting started as much a self +service process as possible with frequently asked questions answered in standard +documentation format. + +### README.md + +If it does not yet exist, create a `README.md` for your project. It should +contain: + +* The [mission of the project](https://producingoss.com/en/producingoss.html#mission-statement) in as a concise format as possible. It should answer what the project's purpose is and enable contributors to make a good first guess whether a suggested feature will likely be in scope for the project, or not. +* A "Getting Started" section for downstream users of the project. It should explain how to setup/ integrate the project artifacts as well as an explanation of some of the first typical steps for first time users. +* Deeper documentation for project users - or a link to that. +* Documentation needed for making modifications to the project - or a link to that. +* Documentation on how to contribute to the project - or a link to that. +* A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used. +* A "Who we are" section explaining who the [Trusted Committers](trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. +* An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists. + + + +### CONTRIBUTING.md + +If the explanation of the steps to make a contribution are too involved, create +a separate `CONTRIBUTING.md` document. This document should answer frequently +asked questions that contributors have asked in the past. There is no need to +provide a comprehensive book up front. Rather, share information that has proven +needed by contributors. Likely it will touch upon one or more of the following +topics: + +* How to checkout the project source code from version control. +* How to make modifications to the project (potentially including information on coding guidelines). +* How to build the project. +* How to run tests to make sure the above modifications aren't introducing new bugs. +* How to submit your modifications back to the project. +* Some information on which turnaround time to expect for modifications made. + + + +### COMMUNICATION.md + +Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. + +Sections in the `COMMUNICATION.md` include points of contact for incoming communications and information about outgoing communications from the project's ownership team. See some examples below. + +Points of contact for incoming communication and how to contact those users: + +* Reporting a bug +* Following up on a PR +* Feature requests +* Questions about documentation +* Escalations + +How and when the team communicates outbound with users and how to get added to those communications: + +* Planned and unplanned outages +* Feature releases +* Code freezes +* Breaking changes + +There are many of good examples for how to write a `README.md` and what kind +of information to include in a `CONTRIBUTING.md` file in various open source projects. +Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), +[Open Source Guide from GitHub](https://opensource.guide/) as well as +the book [Producing Open Source](https://producingoss.com/en/producingoss.html) +all have valuable information on what kind of information to provide. While +Producing Open Source does not have a chapter on writing a good README per se, +the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) +does provide a fairly extensive list of things that fellow host team members, +users and contributors will need. InnerSource projects likely will not cover all +of those aspects right from the start, the list itself is helpful for +inspiration for what one could cover. + +In addition to that, this pattern comes with three very basic templates to get you +started right away: [README-template.md](templates/README-template.md), +[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). + +## Resulting Context + +* The time for contributors to get up to speed is significantly reduced. +* Time spent on answering initial questions for [Trusted Committers](trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. +* Escalations due to misunderstandings and misalignment are significantly reduced. + +## Known Instances + +* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) +* Paypal Inc. +* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). +* Analog Devices Inc. +* Airbus + +## Authors + +* Isabel Drost-Fromm + +## Acknowledgments + +* Katie Schueths - for adding the `COMMUNICATION.md` concept + +## Alias + +Provide standard base documentation through a README + +## Status + +* Structured +* Drafted in December 2019. + +## References + +* [README-template.md](templates/README-template.md) and +* [CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md) + +## Credits + +[Web](https://storyset.com/web) and [People](https://storyset.com/people) illustrations by Storyset ```

Issue Tracker Use Cases (patterns/2-structured/issue-tracker.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/issue-tracker.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/issue-tracker.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **60** days. ```diff # diff --git a/patterns/2-structured/issue-tracker.md b/patterns/2-structured/issue-tracker.md # new file mode 100644 # index 0000000..ffbda05 # --- /dev/null +++ b/patterns/2-structured/issue-tracker.md @@ -0,0 +1,60 @@ +## Title + +Issue Tracker Use Cases + +## Patlet + +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. + +## Problem + +A team develops a component that many teams in the organization depend on. It +uses a standard issue tracker for tracking open bugs and feature requests. +However, the context in each entry is very limited. As a result potential +contributors have no way of knowing what change exactly each issue is talking +about. + +## Context + +The InnerSource project tooling is all setup. However, the project issue tracker +is mainly used for sharing progress. In InnerSource projects there are many more +use cases that an issue tracker can be used for that make remote, asynchronous +communication easier. + +## Forces + +- Contributors would like to understand whether the feature that they are missing is already on the roadmap. With a lot of context missing in issues though it is impossible to decide whether existing issues match the contributing team's needs. +- As a result a lot of duplicate issues are being opened that the host team has to deal with. +- As context in open issues is so limited contributors are unable to help the host team by implementing some easier issues that are open already. As a result a lot of work remains in the hands of the host team. +- With a strong focus on verbal communication it is impossible to discern after a couple months or years why a certain feature was being chosen for implementation. As a result refactorings, in particular simplifying the component becomes an exercise in project archaeology and brain picking of people who remember what was discussed. + +## Solution + +Embrace the "written over verbal" philosophy not only for pure software +development but also during the planning phase of new features: + +- For bugs, planned features and feature ideas create separate issues. In each of those include as much information as possible so that potential external contributors are able to understand the context. Ideally, in particular for easier changes, include enough information for external contributors to support the host team by implementing the functionality in question. +- Potentially use the issue tracker as a channel to ask questions. This is in particular helpful if you are lacking other communication sources to tackle user questions. +- Make use of tags and categories in order to distinguish issues used for different purposes. +- For starting a brainstorming session asynchronously, open an issue for gathering ideas. When discussion is starting to calm down, summarize the points identified in this issue in a separate document. Post that for review as a pull request to drill deeper into individual points that still need clarification. The resulting document can be used to publish the results in other appropriate channels as well as for future reference. +- Most issue tracker implementations allow for issue templates. Make use of those not only to collect commonly needed information for bug reports but also include hints about what kind of information is needed for the other usage types. + +## Resulting Context + +- Making more use of the project's issue tracker for communication enables external contributors to follow along and make better decisions on what to contribute. +- A focus on structured written communication enables host team members to participate remotely. +- Consistently communicating in writing means that passive documentation on project decisions accumulates as a by-product instead of needing added attention. +- Consistently using public communication channels leads to more humans following a discussion. This means that there are more knowledgeable humans that can answer questions, chime in on open issues, or point out flaws in planned features that would otherwise be found only much later. +- Moving discussions to a public discussion medium creates an opportunity for potential future contributors to lurk, follow along, get comfortable and learn the ways of the project long before they have the first need to get involved. + +## Known Instances + +* Europace AG - See blog post [Issue Use Cases](https://tech.europace.de/post/using-issues-for-asking-questions-and-tracking-work/) + +## Authors + +Isabel Drost-Fromm + +## Status + +Structured ```

30 Day Warranty (patterns/2-structured/30-day-warranty.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/30-day-warranty.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **60** days. ```diff # diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md # index 7c2ab75..ce93a1b 100644 # --- a/patterns/2-structured/30-day-warranty.md # +++ b/patterns/2-structured/30-day-warranty.md @@ -34,7 +34,7 @@ Address the fears of both the receiving and the contributing teams by establishi Note that the warranty period could be 45, 60, or 100 days too. The duration may vary based upon the constraints of the project, the software life cycle of the project, commitments to customers, and other factors. -In addition it helps to provide clear [contribution guidelines](./project-setup/base-documentation.md), spelling out the expectations of the receiving team and the contributing team. +In addition it helps to provide clear [contribution guidelines](./base-documentation.md), spelling out the expectations of the receiving team and the contributing team.  ```

Dedicated Community Leader (patterns/2-structured/dedicated-community-leader.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/dedicated-community-leader.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/dedicated-community-leader.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **68** days. ```diff # diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md # index 91f3c3d..8f5235d 100644 # --- a/patterns/2-structured/dedicated-community-leader.md # +++ b/patterns/2-structured/dedicated-community-leader.md @@ -59,6 +59,7 @@ Having excellent and dedicated community leaders is a precondition for the succe ## Known Instances * _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. +* _Airbus_. A data scientist wanted to improve the collaboration with peers in the group and found: i) many developers (beyond data science) wanted that too and were happy someone was taking care of the issue, and ii) support from line manager and middle management to eventually act as the _de facto_ community leader, on top of his regular line of duty. ## Alias ```

Repository Activity Score (patterns/2-structured/repository-activity-score.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/repository-activity-score.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/repository-activity-score.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **60** days. ```diff # diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md # index 27421a6..dae8f3e 100644 # --- a/patterns/2-structured/repository-activity-score.md # +++ b/patterns/2-structured/repository-activity-score.md @@ -115,7 +115,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances * Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). -* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./project-setup/base-documentation.md) and the [InnerSource License](./innersource-license.md). +* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./base-documentation.md) and the [InnerSource License](./innersource-license.md). ## Status ```

Start as an Experiment (patterns/2-structured/start-as-experiment.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/start-as-experiment.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/start-as-experiment.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **68** days. ```diff # diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md # index 53326df..56e0c7d 100644 # --- a/patterns/2-structured/start-as-experiment.md # +++ b/patterns/2-structured/start-as-experiment.md @@ -54,6 +54,7 @@ Finally, starting as an experiment makes it much easier to sidestep regulations ## Known Instances - Robert Bosch GmbH (globally distributed software development) +- Airbus: the data science community collaborated on shared Python libraries that eventually lead to a group-wide InnerSource scheme for any software. ## Status ```

Maturity Model (patterns/2-structured/maturity-model.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/maturity-model.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/maturity-model.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **68** days. ```diff # diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md # index 8e41062..629c2e4 100644 # --- a/patterns/2-structured/maturity-model.md # +++ b/patterns/2-structured/maturity-model.md @@ -213,6 +213,7 @@ long term. * Entelgy * Zylk * Bitergia +* Airbus ## Authors ```

InnerSource License (patterns/2-structured/innersource-license.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-license.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/innersource-license.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...5e711f0133f5f58ab98e4c03b0475c63036e37c8) on GitHub. The number of days since overdue updates is **68** days. ```diff # diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md # index 54b5c55..169ea8a 100644 # --- a/patterns/2-structured/innersource-license.md # +++ b/patterns/2-structured/innersource-license.md @@ -32,6 +32,7 @@ At the time of sharing the source code, it can not be reliably predicted what th - Freedom over using the software leads to competition, and spread of ownership - There are legal contracts in place which cover the sharing of source code. These contracts are not standardized, so they create additional effort in negotiating and understanding for every project. The existing contracts may also not allow sharing source code in an open enough sense to support a true InnerSource approach. - Alternatively, there are no legal contracts in place but source code is shared informally. That might create uncertainty in cases where clarity about ownership and rights and obligations is needed. +- Choosing a restrictive and/or copyleft license can constitute a barrier for InnerSource adoption. Specifically, limiting publication to the organisation might require a costly relicensing procedure prior to transitioning to Open Source. ## Solutions @@ -51,6 +52,12 @@ The license simplifies the conversations within our organization about sharing s ## Known Instances +- **DB Systel** +- **Robert Bosch GmbH** +- **Airbus** + +## DB Systel + DB Systel created their own InnerSource License, see [DB Inner Source License][db-inner-source-license]. They used the [EUPL][eupl], as that offered an open source like starting point, and then worked out the constraints and additional rules required in their specific organizational context. The first legal entities (companies) within the DB AG are using their InnerSource License. @@ -66,6 +73,8 @@ The mentioned collaboration challenges include: It is worth mentioning that so far the software shared under this InnerSource license is mostly tooling, infrastructure, and tools lower in the stack. +## Airbus + Airbus created ad hoc InnerSource licenses to enable InnerSource way of working within a large part of the group. ## Status ```

Communication Tooling (patterns/2-structured/communication-tooling.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/communication-tooling.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/communication-tooling.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **60** days. ```diff # diff --git a/patterns/2-structured/communication-tooling.md b/patterns/2-structured/communication-tooling.md # new file mode 100644 # index 0000000..08b1a33 # --- /dev/null +++ b/patterns/2-structured/communication-tooling.md @@ -0,0 +1,96 @@ +## Title + +Communication Tooling + +## Patlet + +The users of an InnerSource project have trouble getting help and getting in touch with the host team. +By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. + +## Problem + +A team is open to receiving contributions from downstream users of their +component. Coordination and communication happens in an ad hoc fashion though +leading to incoherent information being shared, delays in answers received, +contributors pinging multiple host team members before receiving a definitive +answer. + +## Context + +- A team depends on another team's component. +- It would like to make contributions to that component. +- Even when it happens in writing, communication happens in a 1-on-1 fashion. + +## Forces + +- The host team is interested in receiving contributions and willing to mentor contributors. +- Teams have a strong verbal communication culture and are inexperienced with setting up project specific asynchronous communication channels. +- Communication channels may be aligned with specific groups that should be reached but not by communication purpose. + +## Solution + +The host team should provide company-public, archived, searchable, linkable communication channels that anyone in the company can subscribe to, as there are measurable benefits to supporting open, written communications channels. + +The goal when streamlining communication channels for InnerSource projects +should be to align communication around topics, not around certain sets of +people. + +A project should set up the following communication tooling: + +1. **a dedicated issue tracker** where structured communication, decision-making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow. For further applications of the issue tracker see [Issue Tracker Use Cases](./issue-tracker.md). +2. **public discussion channel(s)** that come with less rigid a structure. Typically, this will be mailing lists, online forums, Q&A systems or even archived chat channels. Usually it is enough to start with just one channel for the project. If traffic increases too much it is helpful to split discussions about project usage from discussions about project development. +3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](./trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. + +While communication can happen outside of those written channels, as much information as possible should be brought back to the asynchronous channels. + +All communication channels should be documented in the project `README.md`. For more details on the use of this file see [Standard Base Documentation](./base-documentation.md). + +The host team members need to make an effort to direct questions that they receive personally (e.g. via email or private chat messages) back to official communication channels. + + + +## Resulting Context + +Setting up and consistently using official asynchronous communication channels +helps create a base level of [passive documentation](https://www.oreilly.com/library/view/understanding-the-innersource/9781491986899/ch04.html) that can be referenced again when similar questions come up again. + +With communication happening in the open others can easily follow project +progress and get active contributing. Others lurking and reading lowers the +barrier to get involved raising the likelihood of receiving contributions. + +With questions being answered in public more people can add their perspective +leading to a complete picture - this includes not only host team members, +but also users of the project. + +Keeping communication in asynchronous channels allows for participants on +different schedules - either due to different time zones or due to different +routines, meeting schedules, team routines - to meaningfully contribute to +the project. + +Answering questions in those channels means that not only other team members +can listen in and provide additional information, it also means that other +users with the same question see (or later find) the previous answer leading +to a lower need to repeat explanations. + +## Known Instances + +* Europace AG +* Paypal Inc. +* Mercado Libre + +## Authors + +Isabel Drost-Fromm + +## Acknowledgment + +Sebastian Spier (for the visual) + +## Status + +* Structured +* Drafted in December 2019. + +## Credits + +[People](https://storyset.com/people) illustrations by Storyset ```

[github-actions[bot]]

i18n Contents Consistency Issue

The following files may have consistency issues with the English version. Please check and update the files.

This issue is created when any of the English patterns have changed (in folder ). It compares the git update history to let you know what updates are overdue. The issue should be closed when the update is complete.

Start as an Experiment (patterns/2-structured/start-as-experiment.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/start-as-experiment.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/start-as-experiment.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **97** days. ```diff # diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md # index 53326df..56e0c7d 100644 # --- a/patterns/2-structured/start-as-experiment.md # +++ b/patterns/2-structured/start-as-experiment.md @@ -54,6 +54,7 @@ Finally, starting as an experiment makes it much easier to sidestep regulations ## Known Instances - Robert Bosch GmbH (globally distributed software development) +- Airbus: the data science community collaborated on shared Python libraries that eventually lead to a group-wide InnerSource scheme for any software. ## Status ```

Issue Tracker Use Cases (patterns/2-structured/issue-tracker.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/issue-tracker.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/issue-tracker.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **89** days. ```diff # diff --git a/patterns/2-structured/issue-tracker.md b/patterns/2-structured/issue-tracker.md # new file mode 100644 # index 0000000..ffbda05 # --- /dev/null +++ b/patterns/2-structured/issue-tracker.md @@ -0,0 +1,60 @@ +## Title + +Issue Tracker Use Cases + +## Patlet + +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. + +## Problem + +A team develops a component that many teams in the organization depend on. It +uses a standard issue tracker for tracking open bugs and feature requests. +However, the context in each entry is very limited. As a result potential +contributors have no way of knowing what change exactly each issue is talking +about. + +## Context + +The InnerSource project tooling is all setup. However, the project issue tracker +is mainly used for sharing progress. In InnerSource projects there are many more +use cases that an issue tracker can be used for that make remote, asynchronous +communication easier. + +## Forces + +- Contributors would like to understand whether the feature that they are missing is already on the roadmap. With a lot of context missing in issues though it is impossible to decide whether existing issues match the contributing team's needs. +- As a result a lot of duplicate issues are being opened that the host team has to deal with. +- As context in open issues is so limited contributors are unable to help the host team by implementing some easier issues that are open already. As a result a lot of work remains in the hands of the host team. +- With a strong focus on verbal communication it is impossible to discern after a couple months or years why a certain feature was being chosen for implementation. As a result refactorings, in particular simplifying the component becomes an exercise in project archaeology and brain picking of people who remember what was discussed. + +## Solution + +Embrace the "written over verbal" philosophy not only for pure software +development but also during the planning phase of new features: + +- For bugs, planned features and feature ideas create separate issues. In each of those include as much information as possible so that potential external contributors are able to understand the context. Ideally, in particular for easier changes, include enough information for external contributors to support the host team by implementing the functionality in question. +- Potentially use the issue tracker as a channel to ask questions. This is in particular helpful if you are lacking other communication sources to tackle user questions. +- Make use of tags and categories in order to distinguish issues used for different purposes. +- For starting a brainstorming session asynchronously, open an issue for gathering ideas. When discussion is starting to calm down, summarize the points identified in this issue in a separate document. Post that for review as a pull request to drill deeper into individual points that still need clarification. The resulting document can be used to publish the results in other appropriate channels as well as for future reference. +- Most issue tracker implementations allow for issue templates. Make use of those not only to collect commonly needed information for bug reports but also include hints about what kind of information is needed for the other usage types. + +## Resulting Context + +- Making more use of the project's issue tracker for communication enables external contributors to follow along and make better decisions on what to contribute. +- A focus on structured written communication enables host team members to participate remotely. +- Consistently communicating in writing means that passive documentation on project decisions accumulates as a by-product instead of needing added attention. +- Consistently using public communication channels leads to more humans following a discussion. This means that there are more knowledgeable humans that can answer questions, chime in on open issues, or point out flaws in planned features that would otherwise be found only much later. +- Moving discussions to a public discussion medium creates an opportunity for potential future contributors to lurk, follow along, get comfortable and learn the ways of the project long before they have the first need to get involved. + +## Known Instances + +* Europace AG - See blog post [Issue Use Cases](https://tech.europace.de/post/using-issues-for-asking-questions-and-tracking-work/) + +## Authors + +Isabel Drost-Fromm + +## Status + +Structured ```

Communication Tooling (patterns/2-structured/communication-tooling.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/communication-tooling.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/communication-tooling.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **89** days. ```diff # diff --git a/patterns/2-structured/communication-tooling.md b/patterns/2-structured/communication-tooling.md # new file mode 100644 # index 0000000..08b1a33 # --- /dev/null +++ b/patterns/2-structured/communication-tooling.md @@ -0,0 +1,96 @@ +## Title + +Communication Tooling + +## Patlet + +The users of an InnerSource project have trouble getting help and getting in touch with the host team. +By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. + +## Problem + +A team is open to receiving contributions from downstream users of their +component. Coordination and communication happens in an ad hoc fashion though +leading to incoherent information being shared, delays in answers received, +contributors pinging multiple host team members before receiving a definitive +answer. + +## Context + +- A team depends on another team's component. +- It would like to make contributions to that component. +- Even when it happens in writing, communication happens in a 1-on-1 fashion. + +## Forces + +- The host team is interested in receiving contributions and willing to mentor contributors. +- Teams have a strong verbal communication culture and are inexperienced with setting up project specific asynchronous communication channels. +- Communication channels may be aligned with specific groups that should be reached but not by communication purpose. + +## Solution + +The host team should provide company-public, archived, searchable, linkable communication channels that anyone in the company can subscribe to, as there are measurable benefits to supporting open, written communications channels. + +The goal when streamlining communication channels for InnerSource projects +should be to align communication around topics, not around certain sets of +people. + +A project should set up the following communication tooling: + +1. **a dedicated issue tracker** where structured communication, decision-making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow. For further applications of the issue tracker see [Issue Tracker Use Cases](./issue-tracker.md). +2. **public discussion channel(s)** that come with less rigid a structure. Typically, this will be mailing lists, online forums, Q&A systems or even archived chat channels. Usually it is enough to start with just one channel for the project. If traffic increases too much it is helpful to split discussions about project usage from discussions about project development. +3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](./trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. + +While communication can happen outside of those written channels, as much information as possible should be brought back to the asynchronous channels. + +All communication channels should be documented in the project `README.md`. For more details on the use of this file see [Standard Base Documentation](./base-documentation.md). + +The host team members need to make an effort to direct questions that they receive personally (e.g. via email or private chat messages) back to official communication channels. + + + +## Resulting Context + +Setting up and consistently using official asynchronous communication channels +helps create a base level of [passive documentation](https://www.oreilly.com/library/view/understanding-the-innersource/9781491986899/ch04.html) that can be referenced again when similar questions come up again. + +With communication happening in the open others can easily follow project +progress and get active contributing. Others lurking and reading lowers the +barrier to get involved raising the likelihood of receiving contributions. + +With questions being answered in public more people can add their perspective +leading to a complete picture - this includes not only host team members, +but also users of the project. + +Keeping communication in asynchronous channels allows for participants on +different schedules - either due to different time zones or due to different +routines, meeting schedules, team routines - to meaningfully contribute to +the project. + +Answering questions in those channels means that not only other team members +can listen in and provide additional information, it also means that other +users with the same question see (or later find) the previous answer leading +to a lower need to repeat explanations. + +## Known Instances + +* Europace AG +* Paypal Inc. +* Mercado Libre + +## Authors + +Isabel Drost-Fromm + +## Acknowledgment + +Sebastian Spier (for the visual) + +## Status + +* Structured +* Drafted in December 2019. + +## Credits + +[People](https://storyset.com/people) illustrations by Storyset ```

30 Day Warranty (patterns/2-structured/30-day-warranty.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/30-day-warranty.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **89** days. ```diff # diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md # index 7c2ab75..ce93a1b 100644 # --- a/patterns/2-structured/30-day-warranty.md # +++ b/patterns/2-structured/30-day-warranty.md @@ -34,7 +34,7 @@ Address the fears of both the receiving and the contributing teams by establishi Note that the warranty period could be 45, 60, or 100 days too. The duration may vary based upon the constraints of the project, the software life cycle of the project, commitments to customers, and other factors. -In addition it helps to provide clear [contribution guidelines](./project-setup/base-documentation.md), spelling out the expectations of the receiving team and the contributing team. +In addition it helps to provide clear [contribution guidelines](./base-documentation.md), spelling out the expectations of the receiving team and the contributing team.  ```

InnerSource License (patterns/2-structured/innersource-license.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-license.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/innersource-license.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...5e711f0133f5f58ab98e4c03b0475c63036e37c8) on GitHub. The number of days since overdue updates is **97** days. ```diff # diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md # index 54b5c55..169ea8a 100644 # --- a/patterns/2-structured/innersource-license.md # +++ b/patterns/2-structured/innersource-license.md @@ -32,6 +32,7 @@ At the time of sharing the source code, it can not be reliably predicted what th - Freedom over using the software leads to competition, and spread of ownership - There are legal contracts in place which cover the sharing of source code. These contracts are not standardized, so they create additional effort in negotiating and understanding for every project. The existing contracts may also not allow sharing source code in an open enough sense to support a true InnerSource approach. - Alternatively, there are no legal contracts in place but source code is shared informally. That might create uncertainty in cases where clarity about ownership and rights and obligations is needed. +- Choosing a restrictive and/or copyleft license can constitute a barrier for InnerSource adoption. Specifically, limiting publication to the organisation might require a costly relicensing procedure prior to transitioning to Open Source. ## Solutions @@ -51,6 +52,12 @@ The license simplifies the conversations within our organization about sharing s ## Known Instances +- **DB Systel** +- **Robert Bosch GmbH** +- **Airbus** + +## DB Systel + DB Systel created their own InnerSource License, see [DB Inner Source License][db-inner-source-license]. They used the [EUPL][eupl], as that offered an open source like starting point, and then worked out the constraints and additional rules required in their specific organizational context. The first legal entities (companies) within the DB AG are using their InnerSource License. @@ -66,6 +73,8 @@ The mentioned collaboration challenges include: It is worth mentioning that so far the software shared under this InnerSource license is mostly tooling, infrastructure, and tools lower in the stack. +## Airbus + Airbus created ad hoc InnerSource licenses to enable InnerSource way of working within a large part of the group. ## Status ```

Dedicated Community Leader (patterns/2-structured/dedicated-community-leader.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/dedicated-community-leader.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/dedicated-community-leader.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **97** days. ```diff # diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md # index 91f3c3d..8f5235d 100644 # --- a/patterns/2-structured/dedicated-community-leader.md # +++ b/patterns/2-structured/dedicated-community-leader.md @@ -59,6 +59,7 @@ Having excellent and dedicated community leaders is a precondition for the succe ## Known Instances * _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. +* _Airbus_. A data scientist wanted to improve the collaboration with peers in the group and found: i) many developers (beyond data science) wanted that too and were happy someone was taking care of the issue, and ii) support from line manager and middle management to eventually act as the _de facto_ community leader, on top of his regular line of duty. ## Alias ```

Repository Activity Score (patterns/2-structured/repository-activity-score.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/repository-activity-score.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/repository-activity-score.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **89** days. ```diff # diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md # index 27421a6..dae8f3e 100644 # --- a/patterns/2-structured/repository-activity-score.md # +++ b/patterns/2-structured/repository-activity-score.md @@ -115,7 +115,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances * Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). -* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./project-setup/base-documentation.md) and the [InnerSource License](./innersource-license.md). +* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./base-documentation.md) and the [InnerSource License](./innersource-license.md). ## Status ```

Standard Base Documentation (patterns/2-structured/base-documentation.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/base-documentation.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/base-documentation.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...afd7d1c1c28cda719a1a42de5172dc37ca8470bf) on GitHub. The number of days since overdue updates is **89** days. ```diff # diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md # new file mode 100644 # index 0000000..bd20b82 # --- /dev/null +++ b/patterns/2-structured/base-documentation.md @@ -0,0 +1,161 @@ +## Title + +Standard Base Documentation + +## Patlet + +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`/`COMMUNICATION.md` enables a +self service process for new contributors, so that they can find the answers to +the most common questions on their own. + +## Problem + +A team wants to share either a freshly started or a preexisting project with +the wider organization and receive contributions to it. Potential contributors +often are lost: They are failing to identify the team's preferred communication +channels. They have trouble quickly making a judgment about whether a new +feature makes sense to be added or not. They have a hard time understanding +exactly which colleagues are currently actively maintaining the project. + +## Context + +A project is to be shared with others as an InnerSource project. In order for +others to be able to understand what the project is about as well as how to +contribute, the project needs to provide some base level documentation. So far +the project is lacking either all documentation or some aspects needed for users +to try it out in a self-service manner as well as for contributors to get up to +speed quickly. + +## Forces + +- The project was converted into an InnerSource project only recently. Before, users were either only internal or on-boarded in personal face-to-face sessions. Equally, people working on the project went through personal on-boarding sessions which do not scale with growing numbers of contributors or remote contributors. As a result, self service documentation is lacking. +- The project was newly created as an InnerSource project. However the host team lacks experience with InnerSource. As a result they need guidance on which information to include in their documentation, where to put that documentation so others can find it and which types of readers to address in their documentation. +- The project was converted into an InnerSource project only recently, the host team has limited experience with InnerSource. As a result, existing documentation addresses a lot of technical aspects. It does not cover communication, coordination, information needed to facilitate transparent planning. +- The project was converted into an InnerSource project only recently. As a result, a lot of implicit knowledge that exists within the team is neither written down nor obvious to contributors. +- A lack of documentation leads to potential contributors taking a long time to get setup and get started. Producing documentation (and keeping it up to date) requires a time investment. Even if the host team relies on contributors to help with lacking documentation, those contributions still need time to review. +- Project members are spending a lot of time answering getting started questions. Maintaining a comprehensive database of what could be considered support questions requires a lot of time and effort though. +- Different teams within the organization have diverging standards for how to format source code and which software patterns to use. As a result contributions often end up getting re-written to a large part or even entirely. Standardizing all of that and enforcing the standard often would require a lot of time and work. +- The added work for repeated explanations and re-writes diminishes the usefulness of the InnerSource approach. +- Frequent escalations due to extra work and delays due to re-writes lead to a big cheese situation. + +## Solution + +Address the need for clearer documentation for new contributors. The goal when +creating this documentation should be to make getting started as much a self +service process as possible with frequently asked questions answered in standard +documentation format. + +### README.md + +If it does not yet exist, create a `README.md` for your project. It should +contain: + +* The [mission of the project](https://producingoss.com/en/producingoss.html#mission-statement) in as a concise format as possible. It should answer what the project's purpose is and enable contributors to make a good first guess whether a suggested feature will likely be in scope for the project, or not. +* A "Getting Started" section for downstream users of the project. It should explain how to setup/ integrate the project artifacts as well as an explanation of some of the first typical steps for first time users. +* Deeper documentation for project users - or a link to that. +* Documentation needed for making modifications to the project - or a link to that. +* Documentation on how to contribute to the project - or a link to that. +* A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used. +* A "Who we are" section explaining who the [Trusted Committers](trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. +* An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists. + + + +### CONTRIBUTING.md + +If the explanation of the steps to make a contribution are too involved, create +a separate `CONTRIBUTING.md` document. This document should answer frequently +asked questions that contributors have asked in the past. There is no need to +provide a comprehensive book up front. Rather, share information that has proven +needed by contributors. Likely it will touch upon one or more of the following +topics: + +* How to checkout the project source code from version control. +* How to make modifications to the project (potentially including information on coding guidelines). +* How to build the project. +* How to run tests to make sure the above modifications aren't introducing new bugs. +* How to submit your modifications back to the project. +* Some information on which turnaround time to expect for modifications made. + + + +### COMMUNICATION.md + +Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently +asked questions about communicating with your team that contributors need to know. The goal is to streamline communications so users and contributors reach out to the correct person through a single channel. This reduces unnecessary distractions for team members and organizes communications so they do not get lost. + +Sections in the `COMMUNICATION.md` include points of contact for incoming communications and information about outgoing communications from the project's ownership team. See some examples below. + +Points of contact for incoming communication and how to contact those users: + +* Reporting a bug +* Following up on a PR +* Feature requests +* Questions about documentation +* Escalations + +How and when the team communicates outbound with users and how to get added to those communications: + +* Planned and unplanned outages +* Feature releases +* Code freezes +* Breaking changes + +There are many of good examples for how to write a `README.md` and what kind +of information to include in a `CONTRIBUTING.md` file in various open source projects. +Pages like [how to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), +[Open Source Guide from GitHub](https://opensource.guide/) as well as +the book [Producing Open Source](https://producingoss.com/en/producingoss.html) +all have valuable information on what kind of information to provide. While +Producing Open Source does not have a chapter on writing a good README per se, +the [Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) +does provide a fairly extensive list of things that fellow host team members, +users and contributors will need. InnerSource projects likely will not cover all +of those aspects right from the start, the list itself is helpful for +inspiration for what one could cover. + +In addition to that, this pattern comes with three very basic templates to get you +started right away: [README-template.md](templates/README-template.md), +[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md). + +## Resulting Context + +* The time for contributors to get up to speed is significantly reduced. +* Time spent on answering initial questions for [Trusted Committers](trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. +* Escalations due to misunderstandings and misalignment are significantly reduced. + +## Known Instances + +* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) +* Paypal Inc. +* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). +* Analog Devices Inc. +* Airbus + +## Authors + +* Isabel Drost-Fromm + +## Acknowledgments + +* Katie Schueths - for adding the `COMMUNICATION.md` concept + +## Alias + +Provide standard base documentation through a README + +## Status + +* Structured +* Drafted in December 2019. + +## References + +* [README-template.md](templates/README-template.md) and +* [CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md) + +## Credits + +[Web](https://storyset.com/web) and [People](https://storyset.com/people) illustrations by Storyset ```

Maturity Model (patterns/2-structured/maturity-model.md)

For more information, please compare [the original file(en)](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/patterns/2-structured/maturity-model.md) with [the translated file](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/blob/master/translation/zh/patterns/maturity-model.md). You can view [the differences](https://github.com/yuhattor-enterprise-org/InnerSourcePatterns/compare/...201704f4fdb30bd44ef42cd3adecb232bd381055) on GitHub. The number of days since overdue updates is **97** days. ```diff # diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md # index 8e41062..629c2e4 100644 # --- a/patterns/2-structured/maturity-model.md # +++ b/patterns/2-structured/maturity-model.md @@ -213,6 +213,7 @@ long term. * Entelgy * Zylk * Bitergia +* Airbus ## Authors ```