diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c426727c9..cb7753883 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -8,7 +8,7 @@ # the repo. Unless a later match takes precedence, # @global-owner1 and @global-owner2 will be requested for # review when someone opens a pull request. -* @lenucksi @nyeates @gruetter @NewMexicoKid @cewilliams @spier +* @lenucksi @NewMexicoKid @cewilliams @spier # Order is important; the last matching pattern takes the most # precedence. When someone opens a pull request that only diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml index 7bf585c90..5af618ba5 100644 --- a/.github/workflows/book.yml +++ b/.github/workflows/book.yml @@ -3,7 +3,8 @@ name: Book ToC Generation on: push: branches: - - "master" + - "main" + - "book-staging" jobs: book-toc-generation: diff --git a/.github/workflows/main.yml b/.github/workflows/link-checker.yml similarity index 70% rename from .github/workflows/main.yml rename to .github/workflows/link-checker.yml index 8ae300776..f82b2bb0e 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/link-checker.yml @@ -6,8 +6,11 @@ name: Link Check on Patterns and README on: push: branches: - - "master" + - "main" pull_request: + schedule: + # * is a special character in YAML so you have to quote this string + - cron: '30 8 * * *' jobs: linkChecker: @@ -18,6 +21,6 @@ jobs: id: lc uses: peter-evans/link-checker@v1 with: - args: -v -d . -x "http://creativecommons.org/licenses|https://isc-inviter.herokuapp.com|https://github.com/rcs/rcs-viewer/pull/81|fearlesschangepatterns.com" README.md patterns/ -r + args: -v -d . -x "http://creativecommons.org/licenses|https://isc-inviter.herokuapp.com|https://github.com/rcs/rcs-viewer/pull/81|fearlesschangepatterns.com|https://ulir.ul.ie/bitstream/handle/10344/4443/Stol_2014_inner.pdf" README.md patterns/ -r - name: Fail if there were link errors run: exit ${{ steps.lc.outputs.exit_code }} diff --git a/.github/workflows/lint-patterns.yml b/.github/workflows/lint-patterns.yml index e64f010f5..a55402a2a 100644 --- a/.github/workflows/lint-patterns.yml +++ b/.github/workflows/lint-patterns.yml @@ -4,7 +4,7 @@ name: Pattern Syntax Validation on: push: branches: - - "master" + - "main" pull_request: paths: - ".github/workflows/lint-patterns.yml" diff --git a/README.md b/README.md index e84e526ab..08914fd3c 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # InnerSource Patterns - + This repository contains the InnerSource Patterns collected by the [InnerSource Commons][isc-website]. These patterns are InnerSource best practices codified in a specific format to make it easy to understand, evaluate, and reuse them. -If you are here for the first time, you may start by reading our most mature patterns, published at [innersourcecommons.gitbook.io/innersource-patterns](https://innersourcecommons.gitbook.io/innersource-patterns/). +If you are here for the first time, you may start by reading our most mature patterns, published at [patterns.innersourcecommons.org](https://patterns.innersourcecommons.org). Below you find [what a pattern is](#what-are-innersource-patterns), a [list of known patterns](#list-of-patterns), and [how to use these patterns](#how-can-you-use-innersource-patterns) in your organization. @@ -30,51 +30,59 @@ The below lists all known patterns. They are grouped into three [maturity levels ### Maturity Level 2: Structured -#### Reviewed Patterns (proven and reviewed) - -* [30 Day Warranty](patterns/2-structured/30-day-warranty.md) - *a pattern for getting a reluctant code-owning team to accept code submissions from outside their team.* +* [30 Day Warranty](patterns/2-structured/30-day-warranty.md) - *When accepting contributions from outside of your own team, there is a natural aversion to taking responsibility for code not written by the team itself. Through the 30 Day Warranty the contributing team consents to provide bug fixes to the receiving team, which will increase the level of trust between both teams and makes it more likely that contributions get accepted.* * [Common Requirements](patterns/2-structured/common-requirements.md) - *Common code in a shared repository isn't meeting the needs of all the project-teams that want to use it; this is solved through requirements alignment and refactoring.* * [Contracted Contributor](patterns/2-structured/contracted-contributor.md) - *Associates wanting to contribute to InnerSource are discouraged from doing so by their line management. Relief is provided by formal contracts and agreements.* * [Dedicated Community Leader](patterns/2-structured/dedicated-community-leader.md) - *Select people with both communications and technical skills to lead the communities to ensure success in starting an InnerSource initiative.* * [Gig Marketplace](patterns/2-structured/gig-marketplace.md) - *Establish a marketplace by creating an intranet website that lists specific InnerSource project needs as "Gigs" with explicit time and skill requirements. This will enable managers to better understand their employee’s time commitment and professional benefits thereby increasing the likelihood of garnering approval to make InnerSource contributions.* * [Maturity Model](patterns/2-structured/maturity-model.md) - *Teams have started adopting InnerSource. The practice is spreading to multiple departments. Understanding of what constitutes an InnerSource project are wide spread though. The solution is to provide a maturity model to allow for teams to go through a self check and discover patterns and practices that they are not yet aware of.* -* [InnerSource License](patterns/2-structured/innersource-license.md) - *Two legal entities that belong to the same organization want to share software source code with each other but they are concerned about the implications in terms of legal liabilities or cross-company accounting. An **InnerSource License** provides a reusable legal framework for the sharing of source code within the organization. This opens up new collaboration options, and makes the rights and obligations of the involved legal entities explicit.* +* [InnerSource License](patterns/2-structured/innersource-license.md) - *Two legal entities that belong to the same organization want to share software source code with each other but they are concerned about the implications in terms of legal liabilities or cross-company accounting. An InnerSource License provides a reusable legal framework for the sharing of source code within the organization. This opens up new collaboration options, and makes the rights and obligations of the involved legal entities explicit.* * [InnerSource Portal](patterns/2-structured/innersource-portal.md) - *Create an intranet website that indexes all available InnerSource project information. This will enable potential contributors to more easily learn about projects that might interest them and for InnerSource project owners to attract an outside audience.* * [Praise Participants](patterns/2-structured/praise-participants.md) - *Thank contributors effectively to engender further engagement from them and to encourage others to contribute* * [Repository Activity Score](patterns/2-structured/repository-activity-score.md) - *The repository activity score is a numeric value that represents the (GitHub) activity of an InnerSource project.* -* [Review Committee](patterns/2-structured/review-committee.md) - *A formal review committee is setup within an org to "officiate" particular inner source projects with resources, etc.* -* [Service vs. Library](patterns/2-structured/service-vs-library.md) - *Teams in a DevOps environment may be reluctant to work across team boundaries on common code bases due to ambiguity over who will be responsible for responding to service downtime. The solution is to realize that often it's -possible to either deploy the same service in independent environments with separate escalation chains in the event of service downtime or factor a lot of shared code out into one library and collaborate on that.* -* [Trusted Committer](patterns/2-structured/trusted-committer.md) - *Many inner-source projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions.* +* [Review Committee](patterns/2-structured/review-committee.md) - *The InnerSource working model is a radical departure from more traditional approaches, for developers and managers alike. By establishing a review committee as an interface between the InnerSource initiative and all senior managers of business units participating in it, the latter are more likely to familiarise themselves with the initiative and support it, as it affords them a certain level of oversight and control without fostering micromanagement.* +* [Service vs. Library](patterns/2-structured/service-vs-library.md) - *Teams in a DevOps environment may be reluctant to work across team boundaries on common code bases due to ambiguity over who will be responsible for responding to service downtime. The solution is to realize that often it's possible to either deploy the same service in independent environments with separate escalation chains in the event of service downtime or factor a lot of shared code out into one library and collaborate on that.* +* [Trusted Committer](patterns/2-structured/trusted-committer.md) - *Many InnerSource projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions.* * [Standard Base Documentation](patterns/2-structured/project-setup/base-documentation.md) - *New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own.* * [Issue Tracker Use Cases](patterns/2-structured/project-setup/issue-tracker.md) - *The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design.* * [Communication Tooling](patterns/2-structured/project-setup/communication-tooling.md) - *An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project team. The idea is to setup and document standard communication tooling that allows for discussions to become visible, archived and searchable.* - -#### Pattern Drafts (proven, not yet fully reviewed) - -* [Assisted Compliance](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/74) - *Helping repo owners be compliant by writing their CONTRIBUTING.md for them as a pull request.* -* [Cross-Team Project Valuation](patterns/2-structured/crossteam-project-valuation.md) - *It's hard to sell the value of cross-team, inner sourced projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it.* -* [Reluctance to Receive Contributions](patterns/1-initial/reluctance-to-accept-contributions.md) - *Core owner of shared asset is reluctant to take contributions due to the required maintenance that comes with them.* -* [What Before How or Services Documentation](https://docs.google.com/document/d/1_N1wsQeDusfIcNy-O2ZXenY3PL7ZbvkUDRZxGUuegZw/edit?usp=drive_web) - *A lack of common understanding between different management tiers creates funding barriers and increases the risk that solutions will not deliver required business outcomes.* -* [Open Source Trumps InnerSource](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/46) - *People find the InnerSource project but, after all things are considered, even if the InnerSource component meets their needs, they still go with the open source component.* -* [Start as Experiment](patterns/2-structured/start-as-experiment.md) - *An inner source initiative is considered but not started, because management is unsure about its outcome and therefore unwilling to commit to the investment.* -* [Include Product Owners](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/71) - *Key Performance Indicators (KPIs) for Product Owners are primarily product focused, and don't consider areas such as collaborative development. This results in a lower level of engagement with inner source projects.* +* [Cross-Team Project Valuation](patterns/2-structured/crossteam-project-valuation.md) - *It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it.* * [Transparent Cross-Team Decision Making using RFCs](patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md) - *InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties.* +* [Start as an Experiment](patterns/2-structured/start-as-experiment.md) - *Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative.* ### Maturity Level 1: Initial * [Modular Code](patterns/1-initial/modular-code.md) - *Management does not want to spend the extra resources needed to develop modular components and make them available in a visible repository for others to use.* -* [Improve Findability](patterns/1-initial/improve-findability.md) - *People can't find the internally developed solutions that they need due to poor naming conventions. This causes frustration in finding inner source solutions and a reduction in code reuse.* +* [Improve Findability](patterns/1-initial/improve-findability.md) - *People can't find the internally developed solutions that they need due to poor naming conventions. This causes frustration in finding InnerSource solutions and a reduction in code reuse.* * [Overcoming Project Management Time Pressures](patterns/1-initial/overcoming-project-management-time-pressures.md) - *Project management believes timeline pressure and commitments on feature content does not allow for developers to spend the time needed to develop shareable code and provide support.* * [Introducing Metrics in InnerSource](patterns/1-initial/introducing-metrics-in-innersource.md) - *Involve all stakeholders in designing and interpreting metrics to measure the current status in terms of health and performance of the InnerSource initiative.* * [Shared Code Repo Different from Build Repo](patterns/1-initial/shared-code-repo-different-from-build-repo.md) - *Deal with the overhead of having shared code in a separate repository that isn't the same as the project-specific one that is tied to production builds.* * [InnerSource Portal - Hygiene](patterns/1-initial/innersource-portal-hygiene.md) - *Allow generation of an official badge for projects intending to be recognised as InnerSource project within your company.* +* [Reluctance to Receive Contributions](patterns/1-initial/reluctance-to-accept-contributions.md) - *Core owner of shared asset is reluctant to take contributions due to the required maintenance that comes with them. Summary pattern that lays out four children patterns with three to be defined.* +* [Include Product Owners](patterns/1-initial/include-product-owners.md) - *Engaging and educating Product Owners about InnerSource can help them modify their actions (e.g., in the space of KPIs) to help InnerSource collaboration work better.* +* [Assisted Compliance](patterns/1-initial/assisted_compliance.md) - *Helping repo owners be compliant by writing their CONTRIBUTING.md for them as a pull request.* +* [Open Source Trumps InnerSource](patterns/1-initial/open-source-trumps-innersource.md) - *Developers disregard InnerSource projects because they consider open source projects to be superior. Introducing a required evaluation of InnerSource projects before choosing an open source project increases the likelihood of the InnerSource projects to be adopted.* +* [Transparent Governance Levels](patterns/1-initial/governance-levels.md) - *There are projects in multiple stages of InnerSource adoption. Contributors get confused when working with projects that are at different stages.* +* [Contained InnerSource](patterns/1-initial/contained-innersource.md) - *Apply InnerSource methods to facilitate collaboration in a cross-divisional project but don't invest in soliciting contributions from outside of that project.* +* [Good First Project](patterns/1-initial/good-first-project.md) - *An InnerSource program has been launched at an organization, and to get off to a successful start it requires some good first projects that lend themselves to InnerSource-style development. Assessing the InnerSource-readiness (fitness) of the candidate projects can help in selecting projects that have the potential to help demonstrate the power of InnerSource.* +* [InnerSource Guidance Group](patterns/1-initial/innersource-guidance-group.md) - *A highly divergent set of development standards in different teams can slow down collaboration betweens these teams. A InnerSource Guidance Group that establishes broad governance and behavioral guidelines can help to reduce these frictions.* +* [Unified Source Code Inventory](patterns/1-initial/source-code-inventory.md) - *In a large organization with different legal entities is often hard to get full visibility into all software assets, in particular all source code. This situation reduces the opportunities to increase business value and keep liability costs, such as software maintenance, under control across the organization as a whole. An organization-level source code inventory addresses these issues while exploiting opportunities to identify and support valuable InnerSource assets.* +* [Explicit Shared Ownership](patterns/1-initial/explicit-shared-ownership.md) - *A software component that several teams depend on has grown to the point where owners are no longer capable of taking full ownership. There is confusion who to involve for changes. Sharing ownership explicitly and making expected behaviour visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership.* +* [Standarized Release Process](patterns/1-initial/release-process.md) - *Teams may be reluctant to use InnerSource projects that they are unfamiliar with when there is no clear release process apparent in the repository. Providing clear release notes and a published artifact (binary, docker image, jar, etc) gives people confidence you are publishing a quality product.* +* [Explicit InnerSource Principles](patterns/1-initial/explicit-innersource-principles.md) - *The usual InnerSource explanation of "applying open source best practices inside an organisation" does not work well with people lacking an open source background. As a remedy the most important principles of InnerSource get published widely.* + + + * [Overcome Acquisition Based Silos - Developers](patterns/1-initial/overcome-acquisition-based-silos-developer.md) * [Overcome Acquisition Based Silos - Managers](patterns/1-initial/overcome-acquisition-based-silos-manager.md) * [Discover Your InnerSource](patterns/1-initial/discover-your-innersource.md) * [Junkyard Styled Inner Sourcing](patterns/1-initial/junkyard-styled-innersourcing.md) * [Incentive Alignment](patterns/1-initial/developer-incentive-alignment-for-innersource-contribution.md) * [Change the Developers Mindset](patterns/1-initial/change-the-developers-mindset.md) +* [Change the Middle-Management Mindset](patterns/1-initial/change-the-middle-management-mindset.md) * [Share Your Code to Get More Done - Likely Contributors Variant](patterns/1-initial/share-your-code-to-get-more-done.md) * [Code Consumers](patterns/1-initial/code-consumers.md) * [Explaining InnerSource to Management by anchoring it to Agile / DevOps / Lean](patterns/1-initial/concept-anchor.md) @@ -86,15 +94,19 @@ possible to either deploy the same service in independent environments with sepa * [Organizational Mindset Change](patterns/1-initial/organizational-mindset-change.md) * [Bad Weather For Liftoff](patterns/1-initial/bad-weather-for-liftoff.md) * [Incentive mechanisms to foster voluntary contribution](patterns/1-initial/incentive-mechanisms-for-voluntary-contribution.md) +* [Duplicated Projects](patterns/1-initial/duplicated-projects.md) ## What are InnerSource Patterns? -Patterns are a way of describing a repeatable, proven solution to a problem with a context. They follow a simple form that helps people wanting to implement the solution to understand the constraints on the problem, the forces that must be balanced and the resulting context (the situation you are left with after the solution is applied). In inner sourcing, patterns can provide a way for the InnerSource Commons participants to concisely share information with each other, improving the practice of inner sourcing. Each of the patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections. +Patterns are a way of describing a repeatable, proven solution to a problem within a context. Patterns follow a simple form that assists you during the implementation of a solution to understand the constraints of the problem, understand the forces you need to balance, and the resulting context - the situation created by applying the solution. -* [`What are patterns?` Youtube videos](http://bit.ly/innersource_patterns_videos) - Watch a set of 2-5 min youtube videos explaining InnerSource Patterns -* [Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU) - We held a webinar 2017-03-16 to live-discuss a donut pattern (go to 24:30 for the discussion). This is an illustration of the review process we follow. Also see the [June 1, 2017 O'Reilly Webinar on InnerSource Patterns](http://www.oreilly.com/pub/e/3884). -* [Pattern Template File](meta/pattern-template.md) - View a skeleton inner source pattern to get an idea on what goes into a new pattern! -* [Introduction to InnerSource Patterns (2016 Fall Summit presentation)](https://drive.google.com/open?id=0B7_9iQb93uBQbnlkdHNuUGhpTXc) - *Tim Yao and Padma Sudarsan* (PDF). Detailed pattern background and examples -- Get a detailed understanding of why and how to interact with our patterns. Also see the [Introduction to InnerSource Patterns (2017 Fall Summit)](https://drive.google.com/open?id=0B7_9iQb93uBQWmYwMFpyaGh4OFU) *Tim Yao and Bob Hanmer* (PDF). +Patterns can provide a way for the InnerSource Commons participants to concisely share information, improving the practice of InnerSource. Patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections. + +* [What are patterns?](https://bit.ly/innersource_patterns_videos) - Watch a set of 2-5 min videos explaining InnerSource Patterns +* [Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU?t=1479) - We held a webinar 2017-03-16 to live-discuss a donut pattern (go to [24:40](https://youtu.be/i-0IVhfRVFU?t=1479) for the discussion). This is an illustration of the review process we follow. Also see the [June 1, 2017 O'Reilly Webinar on InnerSource Patterns](http://www.oreilly.com/pub/e/3884). +* [Pattern Template File](meta/pattern-template.md) - View a skeleton InnerSource pattern to get an idea on what goes into a new pattern! +* [Introduction to InnerSource Patterns (2016 Fall Summit)](https://drive.google.com/open?id=0B7_9iQb93uBQbnlkdHNuUGhpTXc) - *Tim Yao and Padma Sudarsan* (PDF). Detailed pattern background and examples -- Get a detailed understanding of why and how to interact with our patterns. Also see the [Introduction to InnerSource Patterns (2017 Fall Summit)](https://drive.google.com/open?id=0B7_9iQb93uBQWmYwMFpyaGh4OFU) *Tim Yao and Bob Hanmer* (PDF). +* A scientific look at how to write patterns: [A pattern language for pattern writing](http://hillside.net/index.php/a-pattern-language-for-pattern-writing), Meszaros and Doble ## How can you use InnerSource Patterns? @@ -106,10 +118,6 @@ The pattern form is useful for describing proven patterns but it can also be use We welcome your contribution - be it small or huge! To learn more about how you can become a contributor, please see our [CONTRIBUTING.md](CONTRIBUTING.md) file. -## Related References - -* [A pattern language for pattern writing](http://hillside.net/index.php/a-pattern-language-for-pattern-writing), Meszaros and Doble - ## Licensing ![Creative Commons License](https://i.creativecommons.org/l/by-sa/4.0/88x31.png) diff --git a/TRUSTED-COMMITTERS.md b/TRUSTED-COMMITTERS.md index fd343bc16..fab7c6e6f 100644 --- a/TRUSTED-COMMITTERS.md +++ b/TRUSTED-COMMITTERS.md @@ -1,16 +1,31 @@ # Trusted Committers -Trusted committers (TCs) are those members of our working group who have elevated rights and direct write access to this repository. *TCs act as stewards of the working group and community. They aim to make consensus-based decisions in the best interest of the working group.* They also act as the guardians of this repository: TCs react to, referee, and give feedback about incoming contributions. +Trusted Committers (TCs) are those members of our working group who have elevated rights and direct write access to this repository. + +> Trusted Committers act as stewards of the working group and community. They aim to make consensus-based decisions in the best interest of the working group. + +They also act as the guardians of this repository: TCs react to, referee, and give feedback about incoming contributions. + +For further information about the concept, also see the [Trusted Committer Pattern](patterns/2-structured/trusted-committer.md). ## Current Trusted Committers * [@spier](https://github.com/spier) (added 2020-12-11) * [@lenucksi](https://github.com/lenucksi) (added 2020-04-24) -* [@nyeates](https://github.com/nyeates) (added 2017-03-02) -* [@gruetter](https://github.com/gruetter) (added 2017-03-02) * [@NewMexicoKid](https://github.com/NewMexicoKid) (added 2017-03-02) * [@cewilliams](https://github.com/cewilliams) (added 2017-03-02) +## Hall of Fame (aka Alumni) + +While Trusted Committers are in principle appointed for lifetime, interests or priorities of a TC can change and they might not have enough time any more to contribute to the project. + +In those cases we ask them if we should move them to the Hall of Fame. Doing so allows us to appropriately thank them for all of their fantastic contributions. When doing so we also remove them from `.github/CODEOWNERS`, so that reviews of Pull Requests aren't assigned to them anymore, and GitHub notifications are reduced. That increases the clarity for the community who to expect feedback from when creating PRs. + +The alumni in the Hall of Fame can of course always start contributing again in the future and go back to being Trusted Committers if they want to. + +* [@gruetter](https://github.com/gruetter) (added 2017-03-02) +* [@nyeates](https://github.com/nyeates) (added 2017-03-02) + ## Process for Adding new Trusted Committers We work based on trust: Our goal is to add most people who contributed a sizeable change - quick and early. @@ -34,4 +49,6 @@ We follow this process (adapted from [here](https://tech.europace.de/voting-in-n ## Admins -A handful of individuals are currently the technical GitHub Admins for this repository. This includes most members of the InnerSource Commons' #tech-infra team and members of the [InnerSource Commons GitHub Organization](https://github.com/innersourcecommons). However, please channel working group-specific requests through the trusted committers. +A handful of individuals are currently the technical GitHub Admins for this repository. This includes most members of the InnerSource Commons' #tech-infra team and members of the [InnerSource Commons GitHub Organization](https://github.com/innersourcecommons). + +However, please channel working group-specific requests through the trusted committers. diff --git a/assets/img/landscape-of-effective-and-efficient-software-development.png b/assets/img/landscape-of-effective-and-efficient-software-development.png new file mode 100644 index 000000000..ff99ad071 Binary files /dev/null and b/assets/img/landscape-of-effective-and-efficient-software-development.png differ diff --git a/assets/img/patterns-steps-and-maturities.png b/assets/img/patterns-steps-and-maturities.png deleted file mode 100644 index 872aad73d..000000000 Binary files a/assets/img/patterns-steps-and-maturities.png and /dev/null differ diff --git a/assets/img/review-committee-sketch.jpg b/assets/img/review-committee-sketch.jpg index 9e55121f0..9cc317bb5 100644 Binary files a/assets/img/review-committee-sketch.jpg and b/assets/img/review-committee-sketch.jpg differ diff --git a/assets/img/source-code-inventory-mockup-dashboard.PNG b/assets/img/source-code-inventory-mockup-dashboard.PNG new file mode 100644 index 000000000..ba23f3a77 Binary files /dev/null and b/assets/img/source-code-inventory-mockup-dashboard.PNG differ diff --git a/assets/img/source-code-inventory-mockup-questionnaire.PNG b/assets/img/source-code-inventory-mockup-questionnaire.PNG new file mode 100644 index 000000000..8be251877 Binary files /dev/null and b/assets/img/source-code-inventory-mockup-questionnaire.PNG differ diff --git a/assets/img/thirtydaywarranty.jpg b/assets/img/thirtydaywarranty.jpg index 08ee4cf62..f9915fc20 100644 Binary files a/assets/img/thirtydaywarranty.jpg and b/assets/img/thirtydaywarranty.jpg differ diff --git a/book/README.md b/book/README.md index dcc5ae680..6f6dc76f6 100644 --- a/book/README.md +++ b/book/README.md @@ -1,44 +1,42 @@ # How to generate the InnerSource Patterns gitbook -Whenever changes to the [InnerSource Patterns][InnerSourcePatterns] GitHub repository are made, a new version of our InnerSource Patterns book is published at gitbook.com. - -The files in the `./book` folder contain generator scripts and some extra content required to create our gitbook. +Whenever changes to the [InnerSource Patterns][InnerSourcePatterns] GitHub repository are made, a new version of our InnerSource Patterns book is published at [patterns.innersourcecommons.org][book_production]. ## Where is the book published? -The most up-to-date version of the book is available for readers/consumers at [innersourcecommons.gitbook.io/innersource-patterns/][book_production]. - -*NOTE:* -The final URL of the book has not been determined yet. +The most up-to-date version of the book is available for readers/consumers at [patterns.innersourcecommons.org][book_production]. -We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes. +We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes. If you want to make any structural changes to the book, please send a PR to merge your changes into the `book-staging` branch. That way we can test your changes on the Staging version first, before they go live. ## Which patterns are published? -In the book we publish the patterns of maturity **Structured** (Level 2) or **Validated** (Level 3). For more on these maturity levels see the [Contributor Handbook](../meta/contributor-handbook.md). +The book contains patterns of maturity **Structured** (Level 2) or **Validated** (Level 3). **Initial** (Level 1) patterns are not published in the book, because those are still subject to a lot of change, and have likely not even proven to work yet. For more on these maturity levels see the [Contributor Handbook](../meta/contributor-handbook.md). ## How does it work? +The `./book` folder contains generator scripts and some extra content required to create the gitbook. + - `/.gitbook.yaml` - Holds basic configuration for the gitbook service. This never needs to be changed. - `/book/toc.md` - An auto-generated table of contents (ToC) for the book i.e. a list of all pages and patterns that are part of the book. The ToC is what you see on the left-hand-side menu in gitbooks. - `/book/generate_toc.rb` - Takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/toc_template.md`. The output is written to `/book/toc.md`. - `.github/workflows/book.yml` - A GitHub Action that triggers the execution of `/book/generate_toc.rb`. - `/book/introduction.md` - The introduction to our book. This content is what the reader sees first when they open the book. The current content is based on [README.md](../README.md). We may need to modify this content even further, to address the readers of the book more specifically, rather than the readers of our GitHub repository. -- `/book/contribute-to-this-book.md` - Information about how to contribute to this book. +- `/book/contribute.md` - Information about how to contribute to this book. ## Objectives of the book These patterns are already publicly available in the [InnerSource Patterns][InnerSourcePatterns] GitHub repo. So why publish such a book at all? -We think there are a couple of good reasons to publish the InnerSource patterns as a gitbook: +There are a couple of good reasons to publish the InnerSource patterns as a gitbook: * (consumers) have something that is “nicer” to read than things on GitHub -* (consumers) have stable URLs for patterns i.e. even if the files move in the folder structure in the repo, the URL of the pattern stay the same +* (consumers) search for keywords across all patterns * (consumers) export book as PDF and read on other devices -* (producers) a motivation for pattern authors (and all contributors) to level up patterns from 1-initial, as only 2-structured and 3-validated are published in the book +* (consumers) have stable URLs for patterns that can be used as references in other material e.g. from the Learning Path (i.e. even if the files move in the folder structure in the GitHub repo, the URL of the pattern stay the same) +* (producers) a motivation for pattern authors and all contributors to level up patterns from 1-initial, as only 2-structured and 3-validated are published in the book * (producers) a motivation for us to introduce more specific quality guidelines for level 2+3, so that we can be even more proud of the content in the book :) * (producers) learn which patterns are most interesting for readers (e.g. through Google Analytics) [InnerSourcePatterns]: https://github.com/InnerSourceCommons/InnerSourcePatterns -[book_production]: https://innersourcecommons.gitbook.io/innersource-patterns/ -[book_staging]: https://innersourcecommons.gitbook.io/innersource-patterns-staging/v/book/ +[book_production]: https://patterns.innersourcecommons.org +[book_staging]: https://innersourcecommons.gitbook.io/innersource-patterns-staging/v/book-staging/ diff --git a/book/contribute-to-this-book.md b/book/contribute-to-this-book.md deleted file mode 100644 index 7484c09ee..000000000 --- a/book/contribute-to-this-book.md +++ /dev/null @@ -1,27 +0,0 @@ -# Contribute to this book - -You want to help us make this book better? That is awesome! - -The InnerSource Patterns book itself is an open source project, and welcomes any form of contribution. Nothing is too small! - -If you have never made a contribution to an open source project before, know that the InnerSource Patterns community is group of friendly people and with that a safe place to try it out :) - -## Before you get started - -As the sources for the InnerSource Patterns and this book are kept in a repository on GitHub, you will need a user account there to make edits and suggestions to this book. If you don't have a user account at GitHub yet, head over to [github.com](https://github.com) and create one for free. - -## Different ways to contribute - -Here a few ways in which you can contribute: - -1. fix spelling, formatting, or other glitches that you notice in this book -2. improve the content of an existing pattern (e.g. by adding a short description of how you are using a pattern as a _Known Instance_) -3. contribute a new pattern, describing how you have overcome InnerSource-related challenges in your organization - -For (1) and (2) above you can simply hit the **Edit on GitHub** link that you see at the top of each page in the book. This will take you straight to the respective file in our GitHub repository, where you can suggest your changes. - -For (3) you need to clone the [InnerSourcePatterns](https://github.com/InnerSourceCommons/InnerSourcePatterns) repository, and add a new file with your suggested pattern. When making such larger contributions to this book please review our [CONTRIBUTING.md](../CONTRIBUTING.md) and also our [Contributor Handbook](../meta/contributor-handbook.md). - -## License of Contributions - -The contents of this repository are licensed under [CC-BY-SA-4.0](../LICENSE.txt). By contributing to this repository, you grant us (and everyone else for that matter) the right to use your contribution in accordance with that license. diff --git a/book/contribute.md b/book/contribute.md new file mode 100644 index 000000000..07713f642 --- /dev/null +++ b/book/contribute.md @@ -0,0 +1,31 @@ +# Contribute to this book + +You want to make this book better? That is awesome! + +The InnerSource Patterns book itself is an [open source project][repo], and welcomes any form of contribution. Nothing is too small! + +No matter if you want to help us fix grammar/spelling, improve the design, or contribute entirely new patterns based on the InnerSource experiences that you have made at your workplace. We love all of that! :) + +If you have never made a contribution to an open source project before, know that the InnerSource Patterns community is group of friendly people and with that a safe place to try it out. + +## Before you get started + +The sources for the InnerSource Patterns and this book are kept in a repository on GitHub. Therefore you will need a GitHub user account to make edits and suggestions to this book. If you don't have one yet, head over to [github.com](https://github.com) and create an account for free. + +## Different ways to contribute + +Here a few ways in which you can contribute: + +1. fix spelling, formatting, or other glitches that you notice in this book +2. improve the content of an existing pattern (e.g. by adding a short description of how you are using a pattern as a _Known Instance_) +3. contribute a new pattern, describing how you have overcome InnerSource-related challenges in your organization + +For (1) and (2) above you can simply hit the **Edit on GitHub** link that you see at the top of each page in this book. This will take you straight to the respective file in our GitHub repository, where you can suggest your changes. + +For (3) you need to clone the [InnerSourcePatterns][repo] repository, and add a new file with your suggested pattern. When making such larger contributions to this book please review our [CONTRIBUTING.md](../CONTRIBUTING.md) and also our [Contributor Handbook](../meta/contributor-handbook.md). + +## License of Contributions + +The contents of this repository are licensed under [CC-BY-SA-4.0](../LICENSE.txt). By contributing to this repository, you grant us (and everyone else for that matter) the right to use your contribution in accordance with that license. + +[repo]: https://github.com/InnerSourceCommons/InnerSourcePatterns diff --git a/book/explore-patterns.md b/book/explore-patterns.md new file mode 100644 index 000000000..c3670d9e9 --- /dev/null +++ b/book/explore-patterns.md @@ -0,0 +1,19 @@ +# Explore Patterns + +More and more patterns are contributed to this book by the InnerSource Commons community. That is awesome! + +Now how to make it easy for readers to discover the patterns that can help them in their particular situation? + +For this purpose we provide this mind map. It **categorizes patterns based on the different phases of an InnerSource Program**, and the challenges that might appear in the respective phases. + + + +## Improve this Mind Map + +If you notice anything in this mind map that looks wrong, please [open an issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues), describing the problem and the fix that should be made. + +Further if you have other ideas for improving the discoverability of these patterns, or want to make this mind map better, review the documentation of our [Pattern Categorization](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/pattern-categorization/README.md) approach, and also check how to [contribute to this book](contribute.md). + +## References + +The idea for categorizing patterns like this is loosely based a description in [Thoughts on an InnerSource Pattern Language](https://drive.google.com/file/d/13AY8glCOdpLOVuz7cVD6QOB8d2xbHCS1/view) by Tim Yao, Bob Hanmer and Padma Sudarsan (2018). For specifics see slide 15 in that slide deck. diff --git a/book/innersource-patterns-book-cover.jpg b/book/innersource-patterns-book-cover.jpg index b9352cf17..9c62fde54 100644 Binary files a/book/innersource-patterns-book-cover.jpg and b/book/innersource-patterns-book-cover.jpg differ diff --git a/book/innersource-program-mind-map.png b/book/innersource-program-mind-map.png index bd3d7229c..43a44a022 100644 Binary files a/book/innersource-program-mind-map.png and b/book/innersource-program-mind-map.png differ diff --git a/book/introduction.md b/book/introduction.md index aed6a0f6e..64502aac4 100644 --- a/book/introduction.md +++ b/book/introduction.md @@ -3,36 +3,35 @@ {% hint style="info" %} -This is an early release of the InnerSource Patterns book. -You may still find broken links, spelling mistakes, or other errors in this book. -Please help us to fix them to produce the best book possible :). Learn how to [contribute to this book](../book/contribute-to-this-book.md). +You are reading an early release of the InnerSource Patterns book and may still find broken links, spelling mistakes, or other errors. +Please help us to fix them to produce the best book possible :). Learn how to [contribute to this book](../book/contribute.md). {% endhint %} -Welcome to the **InnerSource Patterns book**. +Welcome to the **InnerSource Patterns Book**. This book contains InnerSource best practices codified in a specific format to make it easy to understand, evaluate, and apply them in your context. We call this format a **pattern**. -These patterns have been collected by the [InnerSource Commons](http://innersourcecommons.org) community over many years. The most mature patterns have been published in this book. Mature in this context means that each pattern has been reviewed by members of the community, and has at least one known instance where this pattern has been used. +The [InnerSource Commons](http://innersourcecommons.org) has collected these patterns over many years, publishing the most mature patterns in this book, where members of the community review each pattern, with at least one known instance of pattern use. In this introduction we explain [what InnerSource is](#what-is-innersource), [what a pattern is](#what-are-innersource-patterns), and [how to use these patterns](#how-can-you-use-innersource-patterns) in your organization. -If you are using InnerSource in your company already and want to contribute your experiences to this book we would love to [welcome your contributions](../book/contribute-to-this-book.md)! +If you are using InnerSource in your company already and want to contribute your experiences to this book, we would love to [welcome your contributions](../book/contribute.md)! ## What is InnerSource? We define InnerSource as: -> The use of open source principles and practices for software development within the confines of an organisation. +> The use of open source principles and practices for software development within the confines of an organization. -InnerSource takes the lessons learned from developing open source software and applies them to the way companies develop software internally. As developers have become accustomed to working on world class open source software, there is a strong desire to bring those practices back inside the firewall and apply them to software that companies may be reluctant to release. +InnerSource takes the lessons learned from developing open source software and applies them to the way companies develop software internally. As developers have become accustomed to working on world-class open source software, there is a strong desire to bring those practices back inside the firewall and apply them to software that companies may be reluctant to release. -For companies building mostly closed source software, InnerSource can be a great tool to help break down silos, encourage internal collaboration, accelerate new engineer on-boarding, and identify opportunities to contribute software back to the open source world. +For companies building mostly closed source software, InnerSource can be a great tool to help break down silos, encourage and scale internal collaboration, accelerate new engineer on-boarding, and identify opportunities to contribute software back to the open source world. ## What are InnerSource Patterns? -Patterns are a way of describing a repeatable, proven solution to a problem within a context. They follow a simple form that helps people wanting to implement the solution to understand the constraints on the problem, the forces that must be balanced and the resulting context - the situation created by applying the solution. +Patterns are a way of describing a repeatable, proven solution to a problem within a context. Patterns follow a simple form that assists you during the implementation of a solution to understand the constraints of the problem, understand the forces you need to balance, and the resulting context - the situation created by applying the solution. -In inner sourcing, patterns can provide a way for the InnerSource Commons participants to concisely share information with each other, improving the practice of inner sourcing. Each of the patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections. +Patterns can provide a way for the InnerSource Commons participants to concisely share information, improving the practice of InnerSource. Patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections. * [`What are patterns?` Youtube videos](http://bit.ly/innersource_patterns_videos) - Watch a set of 2-5 min youtube videos explaining InnerSource Patterns * [Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU) - We held a webinar 2017-03-16 to live-discuss a donut pattern (go to 24:30 for the discussion). This is an illustration of the review process we follow. Also see the [June 1, 2017 O'Reilly Webinar on InnerSource Patterns](http://www.oreilly.com/pub/e/3884). @@ -41,19 +40,19 @@ In inner sourcing, patterns can provide a way for the InnerSource Commons partic ## How can you use InnerSource Patterns? -Patterns must be used in a thoughtful manner. They cannot be blindly applied. In most cases, you will need to adapt the given solution to your own situation; but the information given in the pattern, defining the context (immovable constraints) and forces (constraints that can be changed and balanced against each other), should help you do this. Note that you will also need to determine if there are additional constraints (company context and company forces) that apply to your particular company/organization that must be added to the pattern (as a kind of filter). These additional constraints may require additional solution steps to be applied. +Patterns must be used thoughtfully. They cannot be indiscriminately applied. In most cases, you will need to adapt the given solution to your situation; but the information given in the pattern, defining the context (immovable constraints) and forces (constraints that can be changed and balanced against each other), should help you do this. Note that you will also need to determine if there are additional constraints (company context and company forces) that apply to your particular company/organization that must be added to the pattern (as a kind of filter). These additional constraints may require additional solution steps to be applied. -The pattern form is useful for describing proven solutions but it can also be used for *brainstorming new solutions* where patterns are not yet established. This is, because the anatomy of a pattern provides a frame for thinking about a problem in a structured manner. You could also create a *donut pattern* (filling in the problem, context, forces and resulting context fields but leaving the solution blank) as a way of asking the InnerSource Commons community for help (to find a proven solution or to brainstorm things to try). +The pattern form is useful for describing proven solutions but it can also be used for *brainstorming new solutions* where patterns are not yet established. This is because the anatomy of a pattern provides a framework for thinking about a problem in a structured manner. You could also create a *donut pattern* (filling in the problem, context, forces, and resulting context fields but leaving the solution blank) as a way of asking the InnerSource Commons community for help (to find a proven solution or to brainstorm things to try). ## How to Contribute? -Please refer to: [Contribute to this book](./contribute-to-this-book.md) +Please refer to: [Contribute to this book](./contribute.md) ## Credits This book is the result of many years of work from countless [Open Source Contributors](https://github.com/InnerSourceCommons/InnerSourcePatterns/graphs/contributors) from around the world. Their willingness to openly share the challenges that they faced in their companies, and how InnerSource has helped them address those challenges, make this book such a valuable resource for others on their InnerSource journey. -We want to specifically mention the InnerSource Patterns Working Group. They have nurtured the quality of the InnerSource Patterns and helped others to contribute. Lastly they also compiled a selection of available patterns into this book. +We want to specifically mention the InnerSource Patterns Working Group. They have nurtured the quality of the InnerSource Patterns and helped others to contribute. Lastly, they also compiled a selection of available patterns into this book. The title image of this book was created by [Sebastian Spier](https://spier.hu) and adapted from an image by [Tony Hisgett - Alhambra 6](https://www.flickr.com/photos/hisgett/29345405788/), available under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/). diff --git a/book/toc.md b/book/toc.md index 22b1c21ce..8058dfbd0 100644 --- a/book/toc.md +++ b/book/toc.md @@ -11,33 +11,35 @@ Instead edit toc_template.md # Table of Contents * [Table of Contents](../book/toc.md) +* [Explore Patterns](../book/explore-patterns.md) +* [Contribute to this book](../book/contribute.md) -## Patterns +## Patterns * [30 Day Warranty](../patterns/2-structured/30-day-warranty.md) - When accepting contributions from outside of your own team, there is a natural aversion to taking responsibility for code not written by the team itself. Through the 30 Day Warranty the contributing team consents to provide bug fixes to the receiving team, which will increase the level of trust between both teams and makes it more likely that contributions get accepted. * [Common Requirements](../patterns/2-structured/common-requirements.md) - Common code in a shared repository isn't meeting the needs of all the project-teams that want to use it; this is solved through requirements alignment and refactoring. -* [Communication Tooling](../patterns/2-structured/project-setup/communication-tooling.md) - An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project team. The idea is to setup and document standard communication tooling that allows for discussions to become visible, archived and searchable. +* [Communication Tooling](../patterns/2-structured/project-setup/communication-tooling.md) - An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project team. The idea is to set up and document standard communication tooling that allows for discussions to become visible, archived and searchable. * [Contracted Contributor](../patterns/2-structured/contracted-contributor.md) - Associates wanting to contribute to InnerSource are discouraged from doing so by their line management. Relief is provided by formal contracts and agreements. -* [Cross-Team Project Valuation](../patterns/2-structured/crossteam-project-valuation.md) - It's hard to sell the value of cross-team, inner sourced projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it. -* [Dedicated Community Manager](../patterns/2-structured/dedicated-community-leader.md) - Select people with both communications and technical skills to lead the communities to ensure success in starting an InnerSource initiative. +* [Cross-Team Project Valuation](../patterns/2-structured/crossteam-project-valuation.md) - It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it. +* [Dedicated Community Leader](../patterns/2-structured/dedicated-community-leader.md) - Select people with both communications and technical skills to lead the communities to ensure success in starting an InnerSource initiative. * [Gig Marketplace](../patterns/2-structured/gig-marketplace.md) - Establish a marketplace by creating an intranet website that lists specific InnerSource project needs as "Gigs" with explicit time and skill requirements. This will enable managers to better understand their employee’s time commitment and professional benefits thereby increasing the likelihood of garnering approval to make InnerSource contributions. * [InnerSource License](../patterns/2-structured/innersource-license.md) - Two legal entities that belong to the same organization want to share software source code with each other but they are concerned about the implications in terms of legal liabilities or cross-company accounting. * [InnerSource Portal](../patterns/2-structured/innersource-portal.md) - Create an intranet website that indexes all available InnerSource project information. This will enable potential contributors to more easily learn about projects that might interest them and for InnerSource project owners to attract an outside audience. * [Issue Tracker Use Cases](../patterns/2-structured/project-setup/issue-tracker.md) - The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design. -* [Maturity Model](../patterns/2-structured/maturity-model.md) - Teams have started adopting InnerSource. The practice is spreading to multiple departments. Understanding of what constitutes an InnerSource project are wide spread though. The solution is to provide a maturity model to allow for teams to go through a self check and discover patterns and practices that they are not yet aware of. -* [Praise Participants](../patterns/2-structured/praise-participants.md) - After an inner source contribution, it's important to thank the contributor for their time and effort. This pattern gives guidance that not only effectively acknowledges the contribution but also endgenders further engagement from the contributor and others. -* [Repository Activity Score](../patterns/2-structured/repository-activity-score.md) - Potential contributors want to find active InnerSource projects in need of their help. By calculating a repository activity score for each project, a ranked list of projects can be created (e.g. on the InnerSource portal), so that potential contributors can more easily determine which project they want to contribute to. +* [Maturity Model](../patterns/2-structured/maturity-model.md) - Teams have started adopting InnerSource. The practice is spreading to multiple departments. However, the understanding of what constitutes an InnerSource project varies. The solution is to provide a maturity model to allow for teams to go through a self check and discover patterns and practices that they are not yet aware of. +* [Praise Participants](../patterns/2-structured/praise-participants.md) - After an inner source contribution, it's important to thank the contributor for their time and effort. This pattern gives guidance that not only effectively acknowledges the contribution but also engenders further engagement from the contributor and others. +* [Repository Activity Score](../patterns/2-structured/repository-activity-score.md) - Potential contributors want to find active InnerSource projects in need of their help. By calculating a repository activity score for each project, a ranked list of projects can be created (e.g. on the InnerSource Portal), so that potential contributors can more easily determine which project they want to contribute to. * [Review Committee](../patterns/2-structured/review-committee.md) - The InnerSource working model is a radical departure from more traditional approaches, for developers and managers alike. By establishing a review committee as an interface between the InnerSource initiative and all senior managers of business units participating in it, the latter are more likely to familiarise themselves with the initiative and support it, as it affords them a certain level of oversight and control without fostering micromanagement. * [Service vs. Library](../patterns/2-structured/service-vs-library.md) - Teams in a DevOps environment may be reluctant to work across team boundaries on common code bases due to ambiguity over who will be responsible for responding to service downtime. The solution is to realize that often it's possible to either deploy the same service in independent environments with separate escalation chains in the event of service downtime or factor a lot of shared code out into one library and collaborate on that. * [Standard Base Documentation](../patterns/2-structured/project-setup/base-documentation.md) - New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own. * [Start as an Experiment](../patterns/2-structured/start-as-experiment.md) - Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative. -* [Trusted Committer](../patterns/2-structured/trusted-committer.md) - Many inner-source projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions. +* [Transparent Cross-Team Decision Making using RFCs](../patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md) - InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties. +* [Trusted Committer](../patterns/2-structured/trusted-committer.md) - Many InnerSource projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations, project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions. ## Appendix -* [Contribute to this book](../book/contribute-to-this-book.md) * [Pattern Template](../meta/pattern-template.md) * Extras * [README Template](../patterns/2-structured/project-setup/templates/README-template.md) diff --git a/book/toc_template.md b/book/toc_template.md index 6e6c958b2..ad26c067d 100644 --- a/book/toc_template.md +++ b/book/toc_template.md @@ -11,16 +11,17 @@ Instead edit toc_template.md # Table of Contents * [Table of Contents](../book/toc.md) +* [Explore Patterns](../book/explore-patterns.md) +* [Contribute to this book](../book/contribute.md) -## Patterns +## Patterns <> ## Appendix -* [Contribute to this book](../book/contribute-to-this-book.md) * [Pattern Template](../meta/pattern-template.md) * Extras * [README Template](../patterns/2-structured/project-setup/templates/README-template.md) diff --git a/lint/pattern-template.js b/lint/pattern-template.js index 152409bd7..2bbe399ce 100644 --- a/lint/pattern-template.js +++ b/lint/pattern-template.js @@ -21,38 +21,12 @@ module.exports = [ }, { names: ["PATTERN-TEMPLATE-RULE-002"], - description: "Standard Headlines", - tags: ["headings", "headers", "pattern-template"], - function: (params, onError) => { - var allowedHeadlines = "Title|Patlet|Problem|Story|Context|Forces|Solutions|Resulting Context|Known Instances|Status|Author(s)|Acknowledgements"; - var re = new RegExp(`^## (${allowedHeadlines.replace(/(?=[\(\)])/g, '\\')})\\s*$`,"m"); - // console.log(re); - - params.tokens.filter(function filterToken(token) { - return token.type === "heading_open"; - }).forEach(function forToken(token) { - if (token.tag === "h2") { - if (re.test(token.line)) { - return; - } - // if (/^## ()$/m.test(token.line)) { - // return; - // } - - return onError({ - lineNumber: token.lineNumber, - detail: "Allowed types are: " + allowedHeadlines.replace(/\|/g, ', '), - context: token.line - }); - } - }); - } -}, -{ - names: ["PATTERN-TEMPLATE-RULE-003"], description: "Mandatory template sections", + information: new URL("https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/pattern-template.md"), tags: ["headings", "headers", "pattern-template"], function: (params, onError) => { + // A list of all mandatory headlines. + // headline name (from template): regexp of all permitted headline spellings var mandatoryHeadlines = { "Title": "Title", "Patlet": "Patlet", @@ -68,8 +42,8 @@ module.exports = [ var collectedHeadlines = "" - // collect all h2 headlines - // (only the headline text itself, removing markdown sytnax and whitespace) + // Collect all h2 (##) headlines. + // Only the headline text, removing markdown and whitespaces. params.tokens.filter(function filterToken(token) { return token.type === "heading_open"; }).forEach(function forToken(token) { @@ -83,7 +57,7 @@ module.exports = [ } }); - // confirm if all `mandatoryHeadlines` exist exactly once in the `collectedHeadlines` + // confirm if all `mandatoryHeadlines` exist and exist exactly once in the `collectedHeadlines` var errorsFound = []; let headline; diff --git a/lint/pattern-template.yml b/lint/pattern-template.yml index 26f0edf04..e85fb5cb8 100644 --- a/lint/pattern-template.yml +++ b/lint/pattern-template.yml @@ -2,5 +2,4 @@ default: false # excludes all default markdownlint rules # Custom rules: PATTERN-TEMPLATE-RULE-001: true -# PATTERN-TEMPLATE-RULE-002: true # will likely stop using this in favor of rule 003 -PATTERN-TEMPLATE-RULE-003: true +PATTERN-TEMPLATE-RULE-002: true diff --git a/meta/FAQ.md b/meta/FAQ.md index a02363b7b..9e39ab137 100644 --- a/meta/FAQ.md +++ b/meta/FAQ.md @@ -1,8 +1,10 @@ -This is a list of frequently asked questions about InnerSource Patterns +# InnerSource Patterns FAQ + +This is a list of frequently asked questions about InnerSource Patterns. ## What are the different parts of a pattern? What do they mean? -* See the [pattern template](pattern-template.md) (in the *meta* subdirectory) +* See the [pattern template](pattern-template.md) ## Why use a patterns approach to InnerSource? @@ -13,6 +15,7 @@ This is a list of frequently asked questions about InnerSource Patterns * Each organization has its own history (*context*) and culture (a source of *forces*) and even goals, so using a pattern to solve their problems will generally require adaptation of that pattern. Try to identify things about your situation that are unique and apply those as makes sense to the *Context* and *Forces* identified in the pattern. See if these additional constraints might require changes to the *Solution* to ensure that the pattern will work. * Patterns can also be used as a short-hand when discussing InnerSource programs across organizational boundaries. -## I'd like to consult with the IS Patterns community; do I need to have participating members sign NDAs? +## I'd like to consult with the InnerSource Patterns community; do I need to have participating members sign NDAs? -* You could do that, but be aware that the vast majority of IS Patterns meetings are held under the [Chatham House Rule](https://www.chathamhouse.org/chatham-house-rule) that should provide sufficient protection to enable a productive discussion. +* The vast majority of InnerSource Patterns meetings and all conversations in the InnerSource Commons [Slack](https://isc-inviter.herokuapp.com/) are held under the [Chatham House Rule](https://www.chathamhouse.org/chatham-house-rule) that should provide sufficient protection to enable a productive discussion. +* To answer the question directly: No, you don't have to get NDAs signed :) diff --git a/meta/README.md b/meta/README.md index 9df1116f8..835268ba6 100644 --- a/meta/README.md +++ b/meta/README.md @@ -2,13 +2,16 @@ The topics below cover information about how we define, operate, and upkeep this collection of patterns. -* [Pattern Template](./pattern-template.md) - Start a new pattern with a copy of this +* [Contributing](../CONTRIBUTING.md) - How to interact with our group, create your own patterns, or take part in our review-process; GitHub / Web centric instructions + * [Alternate Command-line steps](./technical-git-howto.md) - Contribute a pattern using `git` from the command-line * [Contributor Handbook](./contributor-handbook.md) - Lays out a basic guideline of how to write and contribute a new pattern, including the 3 maturity levels for patterns. -* **(draft)** [Pattern System](./pattern-system.md) - For a human reader it is not easy to digest a long list of patterns. We are working on labeling and classifying the patterns further. +* [Pattern Template](./pattern-template.md) - Start a new pattern with a copy of this +* [FAQ](./FAQ.md) - Frequently asked questions about InnerSource Patterns * [Trusted Committers](../TRUSTED-COMMITTERS.md) - Who these people are, what elevated rights they get, and how you can become one * [Markdown Info](./markdown-info.md) - Markdown is the ascii text format our patterns are written in; this document briefly defines how we use it -* [Contributing](../CONTRIBUTING.md) - How to interact with our group, create your own patterns, or take part in our review-process; Github / Web centric instructions - * [Alternate Command-line steps](./technical-git-howto.md) - If you want to contribute a pattern using `git` from the command-line, this is your document + +## Unfinished documentation + * **(incomplete) Writing Guidelines** - To make the writing for our patterns more consistent, we provide some guidelines to help the various authors to keep a consistent voice. * [InnerSource Spelling](./innersource-spelling.md) - Clarifies the mystery around how to spell this. Spoiler: It is **InnerSource**. -* [FAQ](./FAQ.md) - Frequently asked questions about InnerSource Patterns +* **(draft)** [Pattern System](./pattern-system.md) - For a human reader it is not easy to digest a long list of patterns. We are working on labeling and classifying the patterns further. diff --git a/meta/boardreports/2021-01.md b/meta/boardreports/2021-01.md new file mode 100644 index 000000000..4447d4b02 --- /dev/null +++ b/meta/boardreports/2021-01.md @@ -0,0 +1,93 @@ +# InnerSource Patterns WG - Report for Governance Meeting 2021-01 + +**Reporting Period:** 12/2020 + +## Mission + +*Briefly describe what your project actually does.* + +- Discuss community InnerSource practices and dynamics, collect and document agreed upon best practices of how to do InnerSource - in the form of patterns +- Continuously publish the most mature patterns as an ebook and website + +## Project/Community Status and Health + +*Sum up the status and health of your project and community* + +- 2 new contributors ([@dineshdh](https://github.com/dineshdh), [@nschonni](https://github.com/nschonni)) +- We are merging PRs with minor changes a bit faster already. +- We got more work to do to make contributions easier for new people joining the Patterns WG but we are on a good path. +- Activity and trusted committer diversity is too low to sustain the project in the long run on a high activity level. (Low activity evolution is sustainable.) + +## Project Activity + +*Describe the overall activity in the project over the reporting period.* + +- [InnerSource Patterns book](https://innersourcecommons.gitbook.io/innersource-patterns) is published automatically when new content is pushed to master - @spier +- Added automatic checks to keep the markdown files of the patterns clean + - markdownlint - (#222, #263, thanks [@nschonni](https://github.com/nschonni)) + - Link Checker - @spier + - Finding sensible trade-offs between too strict and too loose checks will be essential. We don't want to scare new contributors away with too many "rules". On the flip side putting some checks into place makes it explicit to contributors what we expect. The hope is that that would speed up some parts of the contribution process. +- Presented at the ISC 2020 APAC Summit: *Level up your InnerSource through Patterns* - @fwan2000, @spier - [video](https://www.youtube.com/watch?v=vSCR13LF6Ww) +- Patterns office-hours concept try out, some success, dual time-zone meeting concept successfully in use in Marketing WG - @lenucksi +- Continuing to work with the new Maturity levels (initial, structured, validated) + +### Pattern-work + +- [Merged PRs](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls?q=is%3Apr+closed%3A2020-12-01..2020-12-31+is%3Amerged+): 22 + - Pattern work: 7 (PRs only) + - #256 add author to Issue Tracker Use Cases Pattern (@spier) + - #239, 240 Book work: Shortening some pattern titles to make for nicer links. Adding some Patlets. (@spier) + - #236, #237 Add link and screenshots to SAP reference implementation. (@Michadelic) + - #213 Adding Elbit Systems as a Known Instance to the InnerSource Portal Pattern. + - #120 Adding Level 1 Pattern: InnerSource Portal - Hygiene (@dineshdh) + - Non-pattern work: 15 (PRs only) + - various cleanup work #222, #263 e.g. adding markdownlint and first linter rules + - some onboarding steps for new Trusted Committer +- [New PRs created](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls?q=is%3Apr+created%3A2020-11-01..2020-11-30): 27 +- [New Issues created](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues?q=is%3Aissue+is%3Aopen+created%3A2020-12-01..2020-12-31+): 2 +- [Issues Closed](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues?q=is%3Aissue+closed%3A2020-12-01..2020-12-31): 6 + +## Plans of the Project + +*Describe the current plans of the project. Include goals the project is working towards as well as any announcements that should be published through the Marketing working group.* + +- Improve [InnerSource Patterns ebook](https://innersourcecommons.gitbook.io/innersource-patterns) further: + - #250 Nicer domain for the book (getting help from @cewilliams) + - Analytics to understand readership better +- Content + - Start "Pattern of the Month" as a way to improve one pattern at a time, do some marketing around the patterns (together with the Marketing WG), and motivate new people to contribute + - Evaluate ideas to further facilitate collection of pattern content (e.g. through automation), channel ongoing discussions into pattern-work and attract more contributors, e.g. by lowering the barriers of entry for them. + - Level up some patterns to higher maturity levels. e.g. the [InnerSource Portal](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-portal.md) has multiple known instances and even a reference implementation now, so it could be brought to maturity "Validated" relatively easily. +- Process / Maintenance + - Onboard further trusted committers + - Review the current list of trusted committers. Some of them don’t seem to be active anymore and likely receive a lot of github notifcations and emails from us that they don't need. (do we have an offboarding process for TCs?) + - Process existing content from PRs and Google group into our repository (once that is done we can focus on the contribution process via the GitHub repo exclusively) + +## Last Committer Addition + +*When was the last committer added to the project? A healthy project tends to add new committers regularly. The report should indicate the most recent date on which a committer was added.* + +- 11th of December 2020: @spier +- 24th of April 2020: @lenucksi + +## Committer Diversity + +*Cover committer diversity in your project. A healthy project should survive the departure of any single contributor or employer of contributors. What are your steps to make sure that people from all regions on the globe can participate in your project without having to be awake at midnight their local time?* + +- Focus on asynchronous collaboration in the #innersource-patterns channel +- Offering office hours on APAC and EU/Americas timeslots +- Work towards automation of administration tasks, documentation of processes +- Have TCs in multiple time zones + +## Legal Issues & Other Needs + +*Are there any project branding or naming issues, either in the project or externally? Any legal issues? Any infrastructure or strategic needs?* + +- **Google Analytics** - can we use it to track readership statistics for our book? (gitbook.com providers Google Analytics tracking natively) +- **Custom Domain** for the book: Out of the box, the book will live at `innersourcecommons.gitbook.io/innersource-patterns`. If we want a custom domain e.g. to drive traffic to innersourcecommons.org, we would have to configure the DNS for a custom domain. Not sure what is possible but e.g. something like `patterns.innersourcecommons.org/` or `books.innersourcecommons.org/innersource-patterns`. Already connected with @cewilliams about this. +- Suggestions welcome on how to attract more contributors. +- Legal: None currently, book illustrations will trigger IP compliance requirements. + +## Any issues for the Board to act on? + +- None diff --git a/meta/boardreports/2021-02.md b/meta/boardreports/2021-02.md new file mode 100644 index 000000000..155dcac6c --- /dev/null +++ b/meta/boardreports/2021-02.md @@ -0,0 +1,100 @@ +# InnerSource Patterns WG - Report for Governance Meeting 2021-02 + +**Reporting Period:** 01/2021 + +## Mission + +*Briefly describe what your project actually does.* + +- Discuss community InnerSource practices and dynamics, collect and document agreed upon best practices of how to do InnerSource - in the form of patterns +- Continuously publish the most mature patterns as an ebook and website + +## Project/Community Status and Health + +*Sum up the status and health of your project and community* + +- new contributors: + - [@dterol23](https://github.com/dterol23) +- We are merging PRs with minor changes a bit faster already. +- We got more work to do to make contributions easier for new people joining the Patterns WG but we are on a good path. +- Activity and trusted committer diversity is too low to sustain the project in the long run on a high activity level. (Low activity evolution is sustainable.) + +## Project Activity + +*Describe the overall activity in the project over the reporting period.* + +**Status: no changes/updates since last report** + +- [InnerSource Patterns book](https://innersourcecommons.gitbook.io/innersource-patterns) is published automatically when new content is pushed to master - @spier +- Added automatic checks to keep the markdown files of the patterns clean + - markdownlint - (#222, #263, thanks [@nschonni](https://github.com/nschonni)) + - Link Checker - @spier + - Finding sensible trade-offs between too strict and too loose checks will be essential. We don't want to scare new contributors away with too many "rules". On the flip side putting some checks into place makes it explicit to contributors what we expect. The hope is that that would speed up some parts of the contribution process. +- Presented at the ISC 2020 APAC Summit: *Level up your InnerSource through Patterns* - @fwan2000, @spier - [video](https://www.youtube.com/watch?v=vSCR13LF6Ww) +- Patterns office-hours concept try out, some success, dual time-zone meeting concept successfully in use in Marketing WG - @lenucksi +- Continuing to work with the new Maturity levels (initial, structured, validated) + +### Pattern-work + +- [Merged PRs](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls?q=is%3Apr+closed%3A2021-01-01..2021-01-31+is%3Amerged+): 18 + - Patterns (aka Content Work): 9 (PRs only) + - #245 Expand RFC Pattern (@tsadler1988) + - #166 initial checkin of concept-anchor (@mishari) + - #71 Create include-product-owners.md (@NewMexicoKid) + - #74 Create assisted_compliance.md (@NewMexicoKid) + - Non-pattern work: 9 (PRs only) + - getting the overview of patterns in the main README into a better shape #254 and #259 +- [New PRs created](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls?q=is%3Apr+created%3A2021-01-01..2021-01-31): 15 +- [New Issues created](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues?q=is%3Aissue+is%3Aopen+created%3A2021-01-01..2021-01-31): 6 +- [Issues Closed](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues?q=is%3Aissue+closed%3A2021-01-01..2021-01-31): 2 + +## Plans of the Project + +*Describe the current plans of the project. Include goals the project is working towards as well as any announcements that should be published through the Marketing working group.* + +**Status: no changes/updates since last report** + +- Improve [InnerSource Patterns ebook](https://innersourcecommons.gitbook.io/innersource-patterns) further: + - #250 Nicer domain for the book (getting help from @cewilliams) + - Analytics to understand readership better +- Content + - Start [Pattern of the Month](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/280) as a way to improve one pattern at a time. Do some marketing around the patterns together with the Marketing WG, and motivate new people to contribute. + - Evaluate ideas to further facilitate collection of pattern content (e.g. through automation), channel ongoing discussions into pattern-work + - Attract more contributors, e.g. by lowering the barriers of entry + - Level up some patterns to higher maturity levels. e.g. the [InnerSource Portal](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-portal.md) has multiple known instances and even a reference implementation now, so it could be brought to maturity "Validated" relatively easily. +- Process / Maintenance + - Onboard further trusted committers + - Process existing content from PRs and Google group into our repository (once that is done we can focus on the contribution process via the GitHub repo exclusively) + +## Last Committer Addition + +*When was the last committer added to the project? A healthy project tends to add new committers regularly. The report should indicate the most recent date on which a committer was added.* + +**Status: no changes/updates since last report** + +- 11th of December 2020: @spier +- 24th of April 2020: @lenucksi + +## Committer Diversity + +*Cover committer diversity in your project. A healthy project should survive the departure of any single contributor or employer of contributors. What are your steps to make sure that people from all regions on the globe can participate in your project without having to be awake at midnight their local time?* + +- Focus on asynchronous collaboration in the #innersource-patterns channel and in the GitHub repo +- Offering office hours on APAC and EU/Americas time slots (@mishari has started to help with the APAC one, also looking to organize a meetup potentially) +- Work towards automation of administration tasks, documentation of processes +- Have Trusted Committers in multiple time zones + +## Legal Issues & Other Needs + +*Are there any project branding or naming issues, either in the project or externally? Any legal issues? Any infrastructure or strategic needs?* + +**Status: no changes/updates since last report** + +- **Google Analytics** - can we use it to track readership statistics for our book? (gitbook.com providers Google Analytics tracking natively) +- **Custom Domain** for the book: Out of the box, the book will live at `innersourcecommons.gitbook.io/innersource-patterns`. If we want a custom domain e.g. to drive traffic to innersourcecommons.org, we would have to configure the DNS for a custom domain. Not sure what is possible but e.g. something like `patterns.innersourcecommons.org/` or `books.innersourcecommons.org/innersource-patterns`. Already connected with @cewilliams about this. +- Suggestions welcome on how to attract more contributors. +- Legal: None currently, book illustrations will trigger IP compliance requirements. + +## Any issues for the Board to act on? + +- None diff --git a/meta/boardreports/2021-05.md b/meta/boardreports/2021-05.md new file mode 100644 index 000000000..899124ea9 --- /dev/null +++ b/meta/boardreports/2021-05.md @@ -0,0 +1,61 @@ +# InnerSource Patterns WG - Report for Governance Meeting 2021-05 + +## Reporting Period + +February 1st - May 15th, 2021 + +## Mission + +*Briefly describe what your project actually does.* + +- Discuss community InnerSource practices and dynamics, collect and document agreed upon best practices of how to do InnerSource - in the form of patterns +- Continuously publish the most mature patterns as an ebook and website + +## Overview + +- the [patterns book](https://patterns.innersourcecommons.org/) has lead to various content improvements. gitbook's "Edit on GitHub" feature seems to make this easier for some contributors. +- patterns get referenced regularly in Slack, especially in #general discussions about InnerSource +- 3 new patterns + 7 new contributors (see below) +- switched to using the `main` branch terminology (instead of `master`) +- gitbook [tweeted](https://twitter.com/GitBookIO/status/1390698860708728836) about our book :) +- office hours run by Mishari (I believe?) / at least 1 person was asking about these in Slack as well. + +## New Patterns + +- [Unified Source Code Inventory](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/source-code-inventory.md) by David Terol from Philips (new contributor) +- [Good First Project](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/good-first-project.md) by Tapajit Dey / Brian Fitzgerald (new contributors) +- [InnerSource Guidance Group](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/innersource-guidance-group.md) by Isabel - thank you for continuously pushing discoveries from Europace into the Patterns format + +## Improving the book + +- [Active voice and typos](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/295) by Doron Katz (new contributor) +- various spelling fixes by Alexander Andrade (new contributor) - not merged yet +- typo fix by [@arlou](https://github.com/arlou) (new contributor) +- removing a duplicate paragraph by Daniela Zheleva (new contributor) +- cleaning up a bunch of old PRs (only 3 left from 2018/2017) + +## Future goals + +- hardening the patterns further, by finding 3 known instances for some of the patterns in the book (improves quality and increases trustworthiness of the patterns) +- level-up more patterns from the GitHub repo to the book. The patterns in the book seem to get more exposure to interested readers. +- trying out other ways to make the patterns easier to discover (e.g. different pattern categories; index pages at the end of the book or similar) +- analytics capabilities for the book, so that we can learn which patterns are most relevant (built-in analytics on gitbook.io are not sufficient) +- try out other forms of engagement around patterns (office hours, "pattern of the month", etc) + +## Last Committer Addition + +*When was the last committer added to the project? A healthy project tends to add new committers regularly. The report should indicate the most recent date on which a committer was added.* + +**Status: no changes/updates since last report** + +- 11th of December 2020: @spier +- 24th of April 2020: @lenucksi + +## Committer Diversity + +*Cover committer diversity in your project. A healthy project should survive the departure of any single contributor or employer of contributors. What are your steps to make sure that people from all regions on the globe can participate in your project without having to be awake at midnight their local time?* + +- Focus on asynchronous collaboration in the #innersource-patterns channel and in the GitHub repo +- Offering office hours on APAC and EU/Americas time slots (@mishari has started to help with the APAC one, also looking to organize a meetup potentially) +- Work towards automation of administration tasks, documentation of processes +- Have Trusted Committers in multiple time zones diff --git a/meta/boardreports/_template.md b/meta/boardreports/_template.md new file mode 100644 index 000000000..5df587772 --- /dev/null +++ b/meta/boardreports/_template.md @@ -0,0 +1,40 @@ +# Quarterly Report for Governance Meeting + +Reminder: The report should not exceed half a page + +## Summary (mandatory) + +| Key Fact | | +| ------------- | ------------- | +| Working Group | *The name of your working group e.g. Patterns* | +| Reporting Period | *e.g. Feb/March/April 2021* | +| Mission | *Briefly describe what your project does.* | +| Last Committer Addition | *When was the last committer added to the project (which date)? A healthy project tends to add new committers regularly.* | + +## Project/Community Status and Health (mandatory) + +Sum up the status and health of your project and community in a few sentences. + +## Project Activity (mandatory) + +Describe the overall activity in the project over the past quarter. + +## Committer Diversity (mandatory if no Committer was added recently) + +In the Patterns Working Group we interpret the term **Committer** here in the sense of [Trusted Committer](../../TRUSTED-COMMITTERS.md). + +A healthy project should survive the departure of any single contributor or employer of contributors. To achieve that it needs a sufficient amount of committer diversity. + +How do you make sure that people from all regions on the globe can participate in your project without having to be awake at midnight their local time? + +## Plans of the Project (optional) + +Describe the current plans of the project. Include goals the project is working towards as well as any announcements that should be published through the Marketing working group. + +## Other Needs (optional) + +Are their any project branding or naming issues, either in the project or externally? Any legal issues? Any infrastructure or strategic needs? + +## Issue for the Board (optional) + +Are there any issues for the Board to act on? diff --git a/meta/pattern-template.md b/meta/pattern-template.md index e753d9d40..703c8778d 100644 --- a/meta/pattern-template.md +++ b/meta/pattern-template.md @@ -4,11 +4,15 @@ Short Title Here ## Patlet -Concise 1-2 sentence description of the problem and solution. Readers may quickly review dozens of these patlets to discover and browse the larger library of patterns. From http://wiki.c2.com/?PatLet +Concise 1-2 sentence description of the problem and solution. +Readers may quickly review dozens of these patlets to discover and browse the larger library of patterns. +From http://wiki.c2.com/?PatLet ## Problem -What is the problem - crisp definition of the problem. Short description, usually not more than a couple sentences, that describes what the issues and challenges are. Be careful not to morph into information found in other sections below. +What is the problem - crisp definition of the problem. +Short description, usually not more than a couple sentences, that describes what the issues and challenges are. +Be careful not to morph into information found in other sections below. ## Story (optional) @@ -16,11 +20,17 @@ Sometimes there is a story that helps people understand the pattern better. ## Context -Where does the problem exist? What are the pre-conditions? **Unchangeable** before the solution goes into place. The content here is often tied to the applicability of the pattern for other readers: "Do I have this same particular situation?" +Where does the problem exist? +What are the pre-conditions? +**Unchangeable** before the solution goes into place. +The content here is often tied to the applicability of the pattern for other readers: "Do I have this same particular situation?" ## Forces -What makes the problem difficult? What are the trade-offs? These are constraints that **can be changed** at a cost. The solution might change one or more of these forces in order to solve the problem, while also in-turn changing the context. +What makes the problem difficult? +What are the trade-offs? +These are constraints that **can be changed** at a cost. +The solution might change one or more of these forces in order to solve the problem, while also in-turn changing the context. ## Sketch (optional) @@ -32,15 +42,20 @@ Verified resolutions and possible resolutions to the problem. ## Resulting Context -What is the situation after the problem has been solved? The original context is changed indirectly by way of the solution. Often this section can include discussion of the next possible Patterns/problems introduced. This section can be short in content - the solution may not introduce new problems or change much context. +What is the situation after the problem has been solved? +The original context is changed indirectly by way of the solution. +Often this section can include discussion of the next possible Patterns/problems introduced. +This section can be short in content - the solution may not introduce new problems or change much context. ## Rationale (optional) -Explains why this is the right solution; using totally different words WHY this solution balances these forces and this context to solve this problem. Can expand on what-if's or theories. +Explains why this is the right solution; using totally different words WHY this solution balances these forces and this context to solve this problem. +Can expand on what-if's or theories. ## Known Instances (optional) -Where has this been seen before? Helps to reinforce that this is a REAL pattern and that you match the context. +Where has this been seen before? +Helps to reinforce that this is a REAL pattern and that you match the context. May mention: @@ -49,18 +64,23 @@ May mention: ## Status (optional until merging) -General pattern status is stored in GitHub's Label tagging - see any pull request. Note that this GitHub label tagging becomes less visible once the pattern is finalized and merged, so having some information in this field is helpful. +General pattern status is stored in GitHub's Label tagging - see any pull request. +Note that this GitHub label tagging becomes less visible once the pattern is finalized and merged, so having some information in this field is helpful. You might store other related info here, such as review history: "Three of us reviewed this on 2/5/17 and it needs John's expertise before it can go further." ## Author(s) (optional) -Often, this is yourself; If you need to, find someone in the InnerSource Commons to be the nominal author (As Told To); Could also be no-one if you do not want to take on authorship (common with a donut looking for a solution) +Often, this is yourself. +If you need to, find someone in the InnerSource Commons to be the nominal author (As Told To). +Could also be no-one if you do not want to take on authorship (common with a donut looking for a solution). ## Acknowledgements (optional) -Include those who assisted in helping with this pattern - both for attribution and for possible future follow up. Though optional, most patterns should list who helped in their creation. +Include those who assisted in helping with this pattern - both for attribution and for possible future follow up. +Though optional, most patterns should list who helped in their creation. ## Alias (optional) -If this pattern is also known under a different name than what is listed unter **Title**, please list those alternative titles here. e.g. if the pattern is named after the problem it solves, a helpful alias might be one that describes the solution that is applied. +If this pattern is also known under a different name than what is listed unter **Title**, please list those alternative titles here. +e.g. if the pattern is named after the problem it solves, a helpful alias might be one that describes the solution that is applied. diff --git a/meta/technical-git-howto.md b/meta/technical-git-howto.md index a4ddd0ddb..ea7b3303d 100644 --- a/meta/technical-git-howto.md +++ b/meta/technical-git-howto.md @@ -1,16 +1,19 @@ # Command-line git steps for creating a new Pattern -If you want to contribute a new pattern, the workflow is done through Branches and Pull Requests (PR's). You can see the available branches on [the branches URL](https://github.com/InnerSourceCommons/InnerSourcePatterns/branches/all) and existing PR's on the [Pull Request page](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls). Branches are meant to separate content, so that multiple people can work all at once. Pull Requests (PR's) are used to bring discussion/review about a specific inner source pattern. +If you want to contribute a new pattern, the workflow is support by these important concepts: -There are indeed multiple ways to start a discussion: +* [Branches](https://github.com/InnerSourceCommons/InnerSourcePatterns/branches/all) are meant to separate content, so that multiple people can work all at once. +* [Pull Requests](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls) (PR's) are used for discussion/review of a specific InnerSource pattern. -* Send a Pull Request for your branch and the maintainers will receive a notification. -* Create an Issue and ask for comments from some of the maintainers. You can mention them using the '@' symbol prior to their github nickname. -* Add reviewers to the Pull Request on the website - this sends requests to review your work +There are multiple ways to start a discussion: -New patterns should use, as their base, the [pattern template file](pattern-template.md). +* Fork the repo, create a branch, and then send a Pull Request for your branch. The maintainers will receive a notification about this automatically. +* Create an [Issue](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues) and ask for comments from some of the [Trusted Committers](../TRUSTED-COMMITTERS.md). You can mention them using the '@' symbol prior to their GitHub username. +* Add reviewers to your Pull Request in GitHub - this sends requests to review your work -Please, when starting a new pattern, make sure that it does not already exist. Take a look at some of the [existing patterns in this repository](/README.md#reviewed-patterns-proven-and-reviewed). +New patterns should use the [pattern template file](pattern-template.md) as their starting point. + +When starting a new pattern, make sure that it does not already exist. Take a look at the [existing patterns in this repository](/README.md#list-of-patterns). ## Overview of steps @@ -20,10 +23,14 @@ The basic steps below can be thought of as *branch*, *commit*, *pull request*, a ## How do you create a branch? -First you need to create a branch (no need to ask for permission!). For this, let's clone the repository: +First you need to create a branch (no need to ask for permission!). + +For this, [create a fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) of this repository. + +Then create a [local clone of your fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#step-2-create-a-local-clone-of-your-fork). ``` -$ git clone https://github.com/InnerSourceCommons/InnerSourcePatterns.git +$ git clone https://github.com/YOUR-USERNAME/InnerSourcePatterns.git ``` Then you should see a message similar to the following one: @@ -86,7 +93,7 @@ $ git checkout -b pattern/ewoks-do-not-hunt $ touch patterns/1-initial/ewoks-do-not-hunt.md ``` -You can fill your [markdown](markdown-info.md) file with the [pattern template text](pattern-template.md) and begin to fill it in with your pattern. +We then fill our [markdown](markdown-info.md) file with the [pattern template text](pattern-template.md) and start to write our pattern. Once our pattern file is ready to go, we need to add the file to the repo and commit that change to our new branch. @@ -96,7 +103,7 @@ $ git add patterns/1-initial/ewoks-do-not-hunt.md $ git commit -m "InnerSource Pattern to deal with Ewoks that do not hunt" ``` -And we should finally upload that branch and file to the server. +And finally we upload that branch and file to the server. ``` $ git push origin pattern/ewoks-do-not-hunt diff --git a/pattern-categorization/README.md b/pattern-categorization/README.md index 0d859c5e8..892108e37 100644 --- a/pattern-categorization/README.md +++ b/pattern-categorization/README.md @@ -6,7 +6,17 @@ Now how do we make it easier for readers to discover the patterns that can help ## InnerSource Program Mind Map -This first categorization effort uses a mind map to categorize patterns based on the different phases of an InnerSource Program, and the challenges that might appear in the respective phases. See [innersource-program-mind-map.html](innersource-program-mind-map.html). Note that this is still in incomplete visualization i.e. it does not contain all of our patterns. +This first categorization effort uses a mind map to categorize patterns based on the different phases of an InnerSource Program, and the challenges that might appear in the respective phases. See [innersource-program-mind-map.html](innersource-program-mind-map.html). Note that this is still an incomplete visualization i.e. it does not contain all of our patterns. + +In the mind map you will see patterns categorized from left to right in increasing levels of detail. + +The logic for these levels is: + +- level 0: the InnerSource program itself (as the root) +- level 1: phase of an InnerSource Program +- level 2: problem category +- level 3: specific problem occurring in an InnerSource context +- level 4: pattern (solution to the problem) To add new patterns to the mind map, edit the source file `innersource-program-mind-map.md`, and then regenerate the visualization like this: @@ -15,6 +25,8 @@ npm install markmap-lib -g markmap innersource-program-mind-map.md ``` +Once this is done please replace `book/innersource-program-mind-map.jpg` with an updated version of this mind map. + ## Future Ideas for Categorization We have some other ideas for categories by which the InnerSource Patterns could be grouped. diff --git a/pattern-categorization/innersource-program-mind-map.html b/pattern-categorization/innersource-program-mind-map.html index 886cc3e4d..22d381919 100644 --- a/pattern-categorization/innersource-program-mind-map.html +++ b/pattern-categorization/innersource-program-mind-map.html @@ -16,10 +16,16 @@ height: 100vh; } - + - + diff --git a/pattern-categorization/innersource-program-mind-map.md b/pattern-categorization/innersource-program-mind-map.md index d34732d60..9c79a6590 100644 --- a/pattern-categorization/innersource-program-mind-map.md +++ b/pattern-categorization/innersource-program-mind-map.md @@ -1,18 +1,30 @@ -# [InnerSource Program](https://innersourcecommons.gitbook.io/innersource-patterns/v/book/toc) +# [InnerSource Program](https://patterns.innersourcecommons.org/toc) ## Begin -### [Start as an Experiment](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/start-as-experiment.md) +### Program Setup -### [Dedicated Community Manager](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/dedicated-community-leader.md) +#### Management hesitates to invest in InnerSource + +##### [Start as an Experiment](https://patterns.innersourcecommons.org/p/start-as-experiment) + +#### Slow community growth hinders InnerSource + +##### [Dedicated Community Leader](https://patterns.innersourcecommons.org/p/dedicated-community-leader) ### Project Setup -#### [Standard Base Documentation](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/project-setup/base-documentation.md) +#### Hard to assess a project quickly + +##### [Standard Base Documentation](https://patterns.innersourcecommons.org/p/base-documentation) -#### [Communication Tooling](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/project-setup/communication-tooling.md) +#### Ad-hoc communication hinders project growth -#### [Issue Tracker Use Cases](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/project-setup/issue-tracker.md) +##### [Communication Tooling](https://patterns.innersourcecommons.org/p/communication-tooling) + +#### Intransparent roadmap and direction of the project + +##### [Issue Tracker Use Cases](https://patterns.innersourcecommons.org/p/issue-tracker) ## Adoption @@ -20,53 +32,57 @@ #### How to measure a project's business value -##### [Cross-Team Project Valuation](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/crossteam-project-valuation.md) +##### [Cross-Team Project Valuation](https://patterns.innersourcecommons.org/p/crossteam-project-valuation) ### Cultural Challenges #### Unrecognized effort -##### [Praise Participants](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/praise-participants.md) +##### [Praise Participants](https://patterns.innersourcecommons.org/p/praise-participants) -##### [Trusted Committer](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/trusted-committer.md) +##### [Trusted Committer](https://patterns.innersourcecommons.org/p/trusted-committer) ### Technical Challenges #### Not meeting everyone's needs -##### [Common Requirements](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/common-requirements.md) +##### [Common Requirements](https://patterns.innersourcecommons.org/p/common-requirements) #### Fear of shared support responsibility -##### [Service vs. Library](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/service-vs-library.md) +##### [Service vs. Library](https://patterns.innersourcecommons.org/p/service-vs-library) ### Organizational Challenges #### Discouragement of contributing resource -##### [Contracted Contributor](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/contracted-contributor.md) +##### [Contracted Contributor](https://patterns.innersourcecommons.org/p/contracted-contributor) #### Rejection of accepting contribution -##### [30 Day Warranty](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) +##### [30 Day Warranty](https://patterns.innersourcecommons.org/p/30-day-warranty) #### Radical change of management -##### [Review Committee](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/review-committee.md) +##### [Review Committee](https://patterns.innersourcecommons.org/p/review-committee) #### Fear of shared support responsibility -##### [Service vs. Library](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/service-vs-library.md) +##### [Service vs. Library](https://patterns.innersourcecommons.org/p/service-vs-library) #### Not enough maintainers to scale -##### [Trusted Committer](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/trusted-committer.md) +##### [Trusted Committer](https://patterns.innersourcecommons.org/p/trusted-committer) + +#### Difficult cross-team coordination + +##### [Transparent Cross-Team Decision Making using RFCs](https://patterns.innersourcecommons.org/p/transparent-cross-team-decision-making-using-rfcs) ### Cross Legal Entities Challenges #### Concern on legal liabilities or cross-company accounting -##### [InnerSource License](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-license.md) +##### [InnerSource License](https://patterns.innersourcecommons.org/p/innersource-license) ## Grow @@ -74,13 +90,13 @@ #### Can't find matching projects -##### [Gig Marketplace](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/gig-marketplace.md) +##### [Gig Marketplace](https://patterns.innersourcecommons.org/p/gig-marketplace) -##### [InnerSource Portal](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/innersource-portal.md) +##### [InnerSource Portal](https://patterns.innersourcecommons.org/p/innersource-portal) #### Difficult to find active projects -##### [Repository Activity Score](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/repository-activity-score.md) +##### [Repository Activity Score](https://patterns.innersourcecommons.org/p/repository-activity-score) ## Scale @@ -88,4 +104,4 @@ #### Not aware of InnerSource best practices -##### [Maturity Model](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/maturity-model.md) +##### [Maturity Model](https://patterns.innersourcecommons.org/p/maturity-model) diff --git a/patterns/1-initial/assisted_compliance.md b/patterns/1-initial/assisted_compliance.md new file mode 100644 index 000000000..9bfd0b58a --- /dev/null +++ b/patterns/1-initial/assisted_compliance.md @@ -0,0 +1,71 @@ +## Title + +Assisted Compliance + +## Patlet + +TBD + +## Problem + +The team that owns the repository doesn't have a `CONTRIBUTING.md`; the task force needs them to have this to submit bug fixes. + +## Context + +* Teams owning the repository are not complying with mandates for having a `CONTRIBUTING.md` +* Compliance guys have to do a job; this is made difficult by teams resisting this. +* Teams owning the repository resist compliance-related mandates for having a `CONTRIBUTING.md`. Having this file is mandated in support of the InnerSource program, to ensure that there is a known and stated process for submitting PRs and having them be appropriately checked and accepted. +* Special task force for security and compliance: developers responsible for fixing these bugs across the company. +* Negotiations are being held but they are slow and little progress is made. +* The task force is discovering the needed information for a `CONTRIBUTING.md` as they investigate the problem. +* There is a checklist for being InnerSource compliant. +* There is a need to be Security compliant. +* There may be export control compliance and legal compliance requirements; a template is provided to repository owners + +## Forces + +* Teams have been resisting this; this ends up wasting time. +* Making documents part of the repo skeleton might be "rubber stamping"; better to have teams own this. So too much automation in this case is bad. + +## Solution + +* Rather than asking the resisting team to do the changes, the policing task force that discovers the lack of compliance create the documentation (in addition to negotiations) +* Taking the contributor perspective (contributors are motivated). They are writing the `CONTRIBUTING.md` documentation for those teams resistant to doing the fixes, doing this as pull requests. The discussion is then documented in the pull request. The resisting development teams then just correct mistakes. +* "Let us help you be compliant" +* You could do an audit to assess the state of compliance. Bots could be used to check compliance; and the state of compliance could show up in an internal portal. + +## Resulting Context + +* Contributors become InnerSource champions; they both teach and guide those through the process in a gentler fashion than it would have been done before. +* Many projects pop up without governance; the first chance to interact with them is to help them setup their `README.md` and be compliant. +* We increase the overall compliance and the chance of getting more contributions from the outside. This ultimately helps the team in question to get more work done. + +## Known Instances + +TBD + +## Status + +Initial + +## Alias + +* Helping repo owners be compliant by writing their CONTRIBUTING.md for them as a pull request +* Let us help you be compliant + +## Authors + +* Silona Bonewald +* Georg Gruetter + +## Acknowledgements + +* Erin Bank +* Tim Yao + +## References + +For anyone starting further work on this pattern, e.g. to level it up to the next maturity, there are some interesting discussions from the time when this pattern was created. + +* Idea to generalize this pattern to include files such as `SUPPORT.md` and `CODE_OF_CONDUCT.md` - see [conversation](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/74#issuecomment-715498921) +* Idea for tooling to automatically generate files such as `CONTRIBUTING.md` - see [conversation](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/74#discussion_r168596722). diff --git a/patterns/1-initial/bad-weather-for-liftoff.md b/patterns/1-initial/bad-weather-for-liftoff.md index 7f675c901..3397188a2 100644 --- a/patterns/1-initial/bad-weather-for-liftoff.md +++ b/patterns/1-initial/bad-weather-for-liftoff.md @@ -25,22 +25,24 @@ TBD - There is a natural tendency to pick low hanging fruits (e. g. tooling) and stop there. - For InnerSource to blossom, a critical mass of experienced developers which can walk the talk is required. -## Sketch (optional) - ## Solution TBD ## Resulting Context -## Rationale (optional) +TBD + +## Known Instances -## Known Instances (optional) +TBD ## Status -Donut +* Initial (Donut) ## Author(s) -* Georg Grütter, Wyane DuPont, Michael Dorner +* Georg Grütter +* Wyane DuPont +* Michael Dorner diff --git a/patterns/1-initial/change-the-developers-mindset.md b/patterns/1-initial/change-the-developers-mindset.md index ad420edde..654325cb5 100644 --- a/patterns/1-initial/change-the-developers-mindset.md +++ b/patterns/1-initial/change-the-developers-mindset.md @@ -8,54 +8,49 @@ TBD ## Problem -* Change developer mindset, it's difficult to push developers to do things. -* Developers are resisting the change, they are in their comfort zone and it's hard to go out. -* Developer organizations maturity is high, so people are used to being in some hierarchy/rules -* Developers are formed in agile, the shift from agile is difficult +* How do you change developer mindset? It's difficult to push developers to do things. +* Developers are resisting the change, they are in their comfort zone and it's hard to get them to go out of it. +* Developer organization's maturity is high, so people are used to being in some hierarchy/rules. +* Developers are formed in Agile, the shift from Agile is difficult. ## Context -* Top-down inner source support -* 3k population of developers -* Middle Management is not supporting inner source -* There's already a successful group in the early stages -* Code visibility is product dependent +* Top-down InnerSource support exists. +* 3k population of developers. +* Middle management is not supporting InnerSource. +* There is already a successful InnerSource group in the early stages. +* Code visibility is product dependent. ## Forces -* Manager are previous developers, so they like the way they were promoted and they want to proceed in similar ways -* Manager restrict where developers can spend time on -* Top-down approach to the inner source -* Different teams within the company have to decide to proceed with inner source -* No formal training -* Processes are not clear - -## Sketch (optional) +* Managers are previous developers, so they like the way they were promoted and they want to proceed in similar ways. +* Managers restrict what developers can spend time on, perhaps because of KPIs they have to meet and their belief in the best way to meet those. +* The approach to the InnerSource initiative is top down - it is supported by top management. +* Different teams within the company decide whether and how to proceed with InnerSource. +* No formal training exists. +* Processes are not clearly defined. ## Solution -* Showing reward/recognition of the developer team -* Formalize training -* Clarify more processes -* Give middle management specific objectives to make inner source successful -* Listen to manager complaints and fears and count on them +* Show reward/recognition of the developer team that is engaged in InnerSource. +* Formalize training. +* Clarify more processes. +* Give middle management specific objectives to make InnerSource successful. +* Listen to manager complaints and fears and counter them. ## Resulting Context -* Use of the several projects across the several development teams -* Collaboration within the same developer team (mentorship and so on) +* Software from several InnerSource projects is used across the several development teams. +* There is improved collaboration within the same developer team (mentorship and so on). -## Rationale (optional) +## Known Instances -## Known Instances (optional) +TBD -## Status +## Status * Initial -* Old status: Unproven -* Old status: Pattern Idea ## See Also -This pattern has been moved for discussion at -https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/63 +* For improving this pattern even further, please also review these [comments from the ISC Fall Summit 2017](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/63#pullrequestreview-67393334). diff --git a/patterns/1-initial/change-the-middle-management-mindset.md b/patterns/1-initial/change-the-middle-management-mindset.md new file mode 100644 index 000000000..0c3bc1e30 --- /dev/null +++ b/patterns/1-initial/change-the-middle-management-mindset.md @@ -0,0 +1,110 @@ +## Title + +Change the Middle-Management Mindset + +## Patlet + +TBD + +## Problem + +The InnerSource program does not live up to its expectations because middle management is reluctant to allocate resources to it. Expectations of the program are faster go-to-market, increased quality, reduced duplicative development, better integration capabilities, and increased developer satisfaction. + +## Context + +* Top down InnerSource support. Embedded in their objectives? Trickling down? Top level management has determined a new KPI around InnerSource and it is cascaded down to middle-management? No. + - a vacuum between top down support and the objectives for developers + - top down support but no one knows what that means +* Developer wants to stand up and be a part of InnerSource projects +* There is no incentive that fits into the middle-management objectives +* Difficult for middle-management to understand how to enable InnerSource; how to work for controlling the direct output of one team to trying to embrace and let evolve an InnerSource community? +* Developers contribute and PO/PM or Scrum Master finds out and puts a wall between developers and the InnerSource project +* Middle-management to support the InnerSource program but higher-priority items keep getting in the way +* Middle-management would rather duplicate than reuse and collaborate; rewriting the fast and easy way is prioritized over participating in a reusable collaboration. + +## Forces + +* Embedded accountability problem: middle managers cannot account for the time they spend and put it in their objectives. Need some metric to make it clear it is worthwhile. Has to become a KPI for them. +* Organizational goals rarely happen with Middle-Management; they write their own goals (or their bosses do); otherwise incentivization happens through budget. Centralized incentivization is very difficult (their other goals will suffer). KPIs tied to people's bottom line can be effective. +* Educational component: propensity is to blame evil middle-management; they may not know how it works and need to understand it. What benefit they will have for having their people involved in InnerSource? +* Managers are afraid of having people stolen from them, of having priorities that aren't theirs, of becoming irrelevant. +* Managers might fear that this will become the wild west (we're the only ones who really care) +* How to manage priorities in such a bazaar? +* Middle-management lacks understanding of what InnerSource implies +* Middle-management has the ability to learn about InnerSource (formalized training) +* Middle-management has a perceived loss of control, as with InnerSource it is less clear to them what the developers are working on. + +## Sketch + +![How to help Middle Managers actively support InnerSource projects involving their people](http://teiru.net/images/middle_management_sketch_img_2257.jpg) + +## Solution + +* [Objectives and key results (OKR)](https://en.wikipedia.org/wiki/OKR) - bigger picture. The best tool ever to get serious traction across business organizations. We are one team; creating durable teams horizontally across Business Units (BUs). Tie middle-management into the OKRs; they can tie these into the quarterly goal (L2s) they write. + * *Editor note: Unclear sentence here* => (WAgile: quarterly we do big planning sessions, L2s are a quarterly goal). Epic for a year, L2 for a quarter. +* Similarly we have goals cascaded down from management levels. Really high level goals have no bearing on daily work of low level developers, but they have traceability to the highest. If you can have InnerSource high level goals cascaded down, you could justify the time. For this to work it is essential that those InnerSource goals don't conflict with existing goals but rather supplement and at best support them. +* Can't get the buzz for InnerSource, but can get buzz for reuse and collaboration (and can measure and show these). Defining the EOL processes. Have incorporated these into the End of Life processes. Majority of the EOLs are due to redundancy. Can counter Middle-Management fear. Fear that they will go away; we clearly define what pieces are theirs to see if there are ways to put competing solutions together. We can EOL something and reuse/collaborate and stop wasting resources. Plays really well to management. + +* Find Trusted Evangelists +* Performance measurement needs to include InnerSource +* OKR/cascading KPIs (proven solution, known to work) + - OKR are bigger picture than KPIs (defined measurement) + - need accountability that transcends from top level goals + - existing goals don't have a cross-BU aspect the way InnerSource does. If we get that, then I can honestly speak to what I'm doing as an individual developer + - shows actual proof of top down support +* Events like three day hackathons where the top down people tell middle-managers that their developers have three free days (middle-managers can't say they don't have support) + - ShipIt Day has a competitive nature (people choose the one idea that is best; everyone else walks away with nothing). Shows an appetite, but not extended out to everybody perpetually. A bit self-defeating. + - We have innovation days (10% time set aside on calendars, broadcast, you can participate). Choose amongst a few and you get three days to form a new team, work on things together. Hackathon for customer-facing or internal projects (prototypes). Could have an InnerSource day where the metric is: Did you work on someone else's code base? Stand it up and then it becomes available for others to use. Come over to collaborate. Opening an issue=1 point; filing a PR= 5 points; 20 points for merging a PR. Then have an award (two weeks off at Hawaii, all paid with your family; or 3-6 months off to work on your own innovative products; or 6 months part time). Every year could have 1-10 people for InnerSource awards--recognition from the CEO. +* Fellows program if you can achieve guest [Trusted Committers](../2-structured/trusted-committer.md); you get one day a week to do cross-platform work (they report on it as a measurement of success rather than a measurement of loss). Planning is good as a part of resource allocation (might have to change expectations; we're one team, a whole group). +* Champions program recruited from any group: could be a Middle-Management champion who has gone through the process before. See who are the new believers. Could put badges on people's names in the directory. Could do cardboard cut-outs of the champion with an InnerSource t-shirt ;-) + +* Built-into the whole design of InnerSource process. Delivery teams don't own any code themselves; they change code amongst the product teams. Middle Management for product teams know that requests will come in for their code to be changed. They need to have their developers provide mentorship to the delivery team developers. We have different BLs; each is represented by a delivery team. Product teams focus on larger architectural decisions, ensure that the delivery teams don't mess too much with the Products. + - We had globalization teams responsible for countries; had constraints (compliance) for each country. Those teams are always good about InnerSource. But for some reason they went away (restructuring). + +* Architectural solutions + - Microservices architecture: creates incentive organizationally for people to collaborate. If a bug occurs, then it creates a problem for the users. + - but it might be violating an SLA if the bug isn't being fixed + - the problem comes with feature requests or affects design (going beyond bug fixes) + - Developing platforms is an ideal InnerSource use case (hackathon to build applications on top) + - SW Architects have to have an InnerSource mentality and work together. + - newer companies with open source developers have that mindset + +* Empowering Middle Management - InnerSource readiness checklist; Middle Management should partner with their developers. What are the opportunities out there. Can we come up with justification for you to spend any time on this (how does this tie together with our KPIs) + +* If the organzation is doing Agile development, during release planning, time and resources for InnerSource practices should be built into sprints. + +* **1 step back, 3 steps forward** (aka "the tax"): If my team contributes, what's the tax (in terms of time/resources)? + * Finding opportunities for contribution + * Making the component reusable (if applicable) + * Supporting your contribution (if applicable) + * Aligning on engagement between teams + * Code submission, reviews & revision + * Documented communication w/consumers or host + * Learning new practices and tools/skills (if applicable) + +## Resulting Context + +* **Support for InnerSource is automatic, standard and expected from Middle Management.** +* More measurement is required; measurement becomes more sophisticated (easier to measure your own stuff; harder to measure others). Keeping track of time spent in projects. +* Better training for Middle Management in negotiation and facilitation will be needed. +* Engineering cost vs. benefit - you will support others; other teams will allow you to make PRs and this will save you time (a balance in the long run.) + +## Known Instances + +TBD + +## Status + +Initial + +## Authors + +* Silona Bonewald +* Max Capraro, FAU +* Sarah Doire, CH Robinson +* Eric Knudtson, Intuit +* Christopher Litsinger, Comcast +* Don McBride, Nokia +* Stephen McCall, Fidelity Investments +* Andrea Peruffo, Nokia +* Tim Yao, Nokia diff --git a/patterns/1-initial/code-consumers.md b/patterns/1-initial/code-consumers.md index 58423f0e2..eaee8ef11 100644 --- a/patterns/1-initial/code-consumers.md +++ b/patterns/1-initial/code-consumers.md @@ -39,11 +39,11 @@ The following are potential solutions that have been proposed to this problem: # Resulting Context -_needs work..?_ +TBD # Known Instances -_needs work...?_ +TBD # Authors diff --git a/patterns/1-initial/concept-anchor.md b/patterns/1-initial/concept-anchor.md index f46901b30..d20153d5a 100644 --- a/patterns/1-initial/concept-anchor.md +++ b/patterns/1-initial/concept-anchor.md @@ -58,11 +58,11 @@ InnerSource helps in this process by its emphasis on a CI/CD workflow as well as ## Resulting Context -**TBD** +TBD ## Status -Donut +* Initial (Donut) ## Author(s) diff --git a/patterns/1-initial/contained-innersource.md b/patterns/1-initial/contained-innersource.md new file mode 100644 index 000000000..30e662a14 --- /dev/null +++ b/patterns/1-initial/contained-innersource.md @@ -0,0 +1,49 @@ +## Title + +Contained InnerSource + +## Patlet + +Apply InnerSource methods to facilitate collaboration in a cross divisional project but don't invest in soliciting contributions from outside of that project. + +## Problem + +Traditional development practices do not work as effectively for cross divisional projects as do InnerSource style practices. However, Management does not support adopting InnerSource practices because it regards efforts for soliciting and facilitating contributions from outside of the project as detrimental for the required efficiency. + +## Context + +* The company plans to develop a new software-intensive product; multiple business units (BUs) are involved in the development of this product +* There is not one single BU which has the required resources or knowledge to do the development on its own. +* An InnerSource program and required tools exist. +* The InnerSource program advocates using the full spectrum of InnerSource practices (we call this _Full Scale InnerSource_ for the purposes of this pattern). + +## Forces + +* The product's importance to company revenue and the committed feature content and dates require a development paradigm that provides known, stable development resources (headcount). +* _Full Scale InnerSource_ includes substantial effort for soliciting and managing contributions as well as onboarding new contributors, which is hard to plan for and may have some effect on the ability to control the timeline for completion and deployment. + +## Solution + +The BUs involved in the development of the new product each dedicate development resources to develop the new product, apply the InnerSource working model and adopt InnerSource tooling to facilitate collaborative development but limit the scope of InnerSource practices to the project. No effort will be spent on facilitating and managing contributions from outside of the project. + +The application of InnerSource is _contained_ to the project. The project may share the developed artifacts outside the project but is not required to do so. + +## Resulting Context + +_Contained InnerSource_ effectively allows and facilitates the +development collaboration of multiple BUs where existing traditional development infrastructure and processes would not have worked efficiently. + +Product development can be successfully completed. Even though _Full Scale InnerSource_ was not implemented and the full benefits from InnerSource practices, such as exemplary documentation which facilitates reuse beyond the project context, are not realized, the project's success still achieves several benefits that wouldn't have been possible through traditional development. In addition, it lends credibility to the concept of InnerSource. + +## Known Instances + +* Large Company + +## Status + +* Initial + +## Author + +* Tim Yao +* Georg Grütter diff --git a/patterns/1-initial/defeat-hierarchical-constraints.md b/patterns/1-initial/defeat-hierarchical-constraints.md index cf3ebe0ee..b26ac86da 100644 --- a/patterns/1-initial/defeat-hierarchical-constraints.md +++ b/patterns/1-initial/defeat-hierarchical-constraints.md @@ -30,6 +30,6 @@ Developers feel empowered to spend at least 20% of their time on inner sourcing ## Status -Donut +* Initial (Donut) ## Author(s) diff --git a/patterns/1-initial/developer-incentive-alignment-for-innersource-contribution.md b/patterns/1-initial/developer-incentive-alignment-for-innersource-contribution.md index 9f722cef0..55a04ab7a 100644 --- a/patterns/1-initial/developer-incentive-alignment-for-innersource-contribution.md +++ b/patterns/1-initial/developer-incentive-alignment-for-innersource-contribution.md @@ -8,7 +8,7 @@ TBD ## Problem -* The organization needs to adopt a more collaborative, open-source like workstyle, but its developers are not properly incentivized or extrinsically motivated to participate in the company’s InnerSource processes. +* The organization needs to adopt a more collaborative, open source like workstyle, but its developers are not properly incentivized or extrinsically motivated to participate in the company’s InnerSource processes. * There is a prevailing attitude in the developer culture that helping or contributing to others' success and learning is a “time sink” or "not my job." * Credit and kudos are not consistently shared with developers who help or contribute to others' success. * Prevailing developer culture is such that many believe the way up the organizational ladder - via increases in title or compensation - depends on one’s performance on quantitative metrics such as lines of code output, deadlines met, ownership of product releases or updates, and so forth. @@ -66,15 +66,13 @@ TBD * devs take on professional mentorship responsibilities for their peers rather than leaving it to non-technical management * career progression clearly identified & understood by engs and management -## Rationale (optional) +## Known Instances -## Known Instances (optional) +TBD ## Status -* Initial -* Old status: Unproven -* Old status: brainstormed solution +* Initial (brainstormed solution) ## Author diff --git a/patterns/1-initial/discover-your-innersource.md b/patterns/1-initial/discover-your-innersource.md index d6ebd03e6..926efe67c 100644 --- a/patterns/1-initial/discover-your-innersource.md +++ b/patterns/1-initial/discover-your-innersource.md @@ -59,6 +59,8 @@ Make it easy to find the reusable code. ## Known Instances +TBD + ## Resulting Context * Internal components are easily visible @@ -70,8 +72,7 @@ Make it easy to find the reusable code. ## Status -* Initial -* Brainstormed pattern idea in progress +* Initial (brainstormed solution) ## Authors diff --git a/patterns/1-initial/duplicated-projects.md b/patterns/1-initial/duplicated-projects.md new file mode 100644 index 000000000..d929d379a --- /dev/null +++ b/patterns/1-initial/duplicated-projects.md @@ -0,0 +1,53 @@ +## Title + +Duplicated Projects + +## Patlet + +TBD + +## Problem + +* Multiple teams are doing InnerSource, but they don't want to work together. +* Multiple teams are working on the same product. How do they merge? + +## Story + +e.g. Splunk. + +* 4 unique products have significant overlap. Discovered after opening them up as InnerSource projects. +* This could apply to more than just InnerSource situations + +## Context + +* Multiple teams (doing InnerSource or not) are trying to tackle the same problem. +* Managers want to run the project in their way. +* Manager B gets upset if something Manager A does breaks B's team. +* It's easier to be mean when you're not face-to-face. + +## Forces + +* People don't want to lose their jobs (or reason for existence). +* Managers can be territorial with their project. +* People rewrite 100% rather than using the 80% that is already there (even though it would be better to InnerSource). +* Related to the [Not Invented Here](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/64) pattern. +* Related to the [Common Requirements](../2-structured/common-requirements.md) pattern. +* It's like buying another company and having duplicate projects. + +## Solutions + +* We are lacking a solution of establishing a baseline (which of the 4 projects is the baseline for the merge)? +* An open and transparent process CI/CD, requirements backlog, deployment, etc. +* Anyone participates in the process in the same way. +* Project lead is assisted by the former managers. +* Move away from (benevolent) dictator (e.g. eng. manager?). Could this be hard to achieve? +* Experience has shown that if people are in the same room then things tend to go better. Not so much by email/phone. You are nicer if you see the people. + +## Resulting Context + +* Managers have been convinced to be a part of the solution. +* Managers are bought in to a process where they have left some control but still retain influence. + +## Status + +* Initial diff --git a/patterns/1-initial/explicit-innersource-principles.md b/patterns/1-initial/explicit-innersource-principles.md new file mode 100644 index 000000000..8b83fe3aa --- /dev/null +++ b/patterns/1-initial/explicit-innersource-principles.md @@ -0,0 +1,164 @@ +## Title + +Explicit InnerSource Principles + +## Patlet + +The usual InnerSource explanation of "applying open source best practices +inside an organisation" does not work well with people lacking an +open source background. As a remedy the most important principles of +InnerSource get published widely. + +## Problem + +The organisation is trying to roll out InnerSource at a larger scale. The +initiative started among open source enthusiasts. The goal is now to get buy-in +from people that are lacking open source experience. For that audience the typical +slogan of "applying open source best practices" is no longer sufficient to +transport the message of what InnerSource is, which problems it solves and which +tools it uses for solving these issues. As a result InnerSource adoption in the +organisation slows down. Teams develop diverging ideas of what the goals of InnerSource +is about and how to best implement it leading to confusion when contributors +are starting to cross team boundaries. + +## Story + +Early experiments in an organisation have shown that open source collaboration +best practices can be beneficial. The next step now is to move the initiative to +teams and individuals lacking a deep background in open source. + +The goal now is to clearly communicate the goals of the InnerSource initiative +as well as a clear path towards achieving these goals. + +## Context + +* InnerSource as a term is circulating among employees. +* The initiative started among open source enthusiasts. + +## Forces + +* Teams have trouble communicating exactly what the important aspects of +InnerSource are. + +* People lacking open source experience fail to understand what it means to bring +open source best practices into the organisation. + +* On a daily basis teams trying to follow InnerSource best practices have a hard +time deciding if what they are doing is inline with general InnerSource values. + +## Solution + +Those driving the InnerSource initiative in the organisation need to help the teams and individuals that are lacking a deep background in open source, and therefore have a less intuitive understanding of InnerSource. + +Clarity should be provided around these two areas: + +### Why does the organisation want to adopt InnerSource? + +In the past InnerSource has proven to be successful to solve several issues +commonly found in organisations. + +However which organizational challenges does your organization hope to improve +upon using InnerSource? + +Instead of going for generalizations, try to exactly identify the solutions +that match the challenges of your organisation - preferably with those affected +by the change you want to see. + +Some challenges that others have addressed by following InnerSource +best practices: + +* Reduce development silos caused by excessive ownership culture. +* Increase innovation speed by reducing time spent solving similar issues by + fostering healthy code reuse. +* Increase development speed by better cross-team collaboration. +* Solve project/ team dependencies beyond "wait it out" and "build workarounds", + thereby reducing engineering bottlenecks. +* Increase quality. +* Increase employee happiness. +* To increase success of new hires. +* To build actionable documentation. + +### Which InnerSource principles will help to address these challenges? + +Once teams understand which problems InnerSource will help them address, the +next step is to explain which principles help address these challenges. + +Based on basic open source development principles the following guidelines +have been proven successful: + +(1) Code must be transparently hosted within the organisation + +Source code, documentation, data relevant for project development must be +available and easy to find for anyone in the organisation. + +(2) Contributions over feature requests + +All stakeholders of a project act as potential contributors and are being +treated and supported as such. Contributions remain suggestions instead of +requirements. Coordination before a contribution helps avoid wasted effort. +Projects provide contribution guidelines to avoid friction. + +(3) Mistakes are opportunities for learning + +With work visible across the entire organisation any mistake is visible to +everyone. As a result a culture must be established in which mistakes are +opportunities for learning instead of failure that should be avoided at all +cost. + +(4) Written over verbal communication + +For projects that span multiple teams, potentially on diverging meeting +schedules, it needs to be possible to collaborate asynchronously. The goal for +InnerSource projects is to recruit new contributors. For that, potential future +contributors need to be able to follow the project progress on a self serve +basis with a very low barrier to entry. If project relevant communication +happens through synchronous communication, arguments discussed need to be made +transparent in the written channel - decisions should be finalized only there. +As a side effect this leads to passive base documentation that is very valuable +for any newcomer to the project. + +(5) Allow written advise to accumulate in a persistent, searchable archive + +All project communication, in particular decisions taken and discussions leading +up to those decisions need to be archived. It must be possible to reference +communication via stable URLs. Previous communication needs to be stored in a +way that can easily be searched. + +Two caveats though: + +1. This does not replace structured documentation. It can serve as a starting point +to collect structured documentation though. + +2. There are exceptions to the rule of everything being written and accessible to +the entire organisation: People related discussions as well as security related +discussions are sensitive and should not be held in public. + +(6) Reward Trusted Committership + +All contributions (e.g. source code, documentation, bug reports, input to +discussions, user support, marketing) are welcome and are being rewarded. +Those showing support for the project are being invited as +[Trusted Committers](../2-structured/trusted-committer.md). All Trusted Committers of a project are published. + +## Resulting Context + +* Organisation members understand which challenges they can address by +applying InnerSource best practices. + +* Organisation members lacking prior open source experience understand the basic +values and principles of InnerSource projects. + +* Organisation members lacking prior open source experience are able to check +their daily doing against a set of common established values. + +* The organisation's development practices become more similar to open source projects thus +making it easier for organisation members to participate in open source +projects. + +## Known Instances + +* Europace AG - see also [Europace InnerSource Prinzipien](https://tech.europace.de/post/europace-inner-source-prinzipien/) (German) + +## Status + +Initial diff --git a/patterns/1-initial/explicit-shared-ownership.md b/patterns/1-initial/explicit-shared-ownership.md new file mode 100644 index 000000000..35677abca --- /dev/null +++ b/patterns/1-initial/explicit-shared-ownership.md @@ -0,0 +1,52 @@ +# Title + +Explicit Shared Ownership + +# Patlet + +A software component that several teams depend on has grown to the point where owners are no longer capable of taking full ownership. There is confusion who to involve for changes. Sharing ownership explicitly and making expected behaviour visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership. + +# Problem + +An organisation is already using InnerSource best practices in several teams. The architecture of the software offered has grown organically. + +While talking about code ownership and accountability, teams notice that there is a component that is in a worrying state: Developed by an original team of authors it has grown it's userbase way beyond what the original team can handle. From time to time others step up to help out, however there is no formal process established. As a result, conflicts arise around who should do the work, and who should decide on project direction. + +Simply forking the component would lead to a lot of duplication and wasted effort. Therefore the involved teams are looking for a less intrusive solution to the issue. + +# Context + +- Teams are working independently but are providing one common platform as a service. + +- The software they are working on has been evolving for a long time. Engineers working on sub-modules have changed over time. + +- One component is in widespread use but ownership is unclear. + +# Forces + +- Ownership of one component is unclear. + +- There are too many teams dependent on the component to pull everyone into one single meeting to discuss ownership. + +- There may be people dependent on the module that are not yet known. +There often is fear around maintenance efforts arising from unwanted attribution to the project. + +# Solution + +Use the issue/ pull-request mechanics that work so well for code modifications to modify the way the component is developed: + +A volunteer creates an issue in the component's repository highlighting the apparent unclarity or even lack of ownership. Subsequently a volunteer (can be the same person) creates a suggestion for how the project should be developed going forward including a proposed list of initial [Trusted Committers](../2-structured/trusted-committer.md). This suggestion is posted to the project's documentation (e.g. it's `README.md` file) as a pull request. This pull request is left open and shared with all people affected by the change. Feedback can be given and integrated asynchronously. Development of the final state is transparent for everyone. + +# Resulting Context + +There is an initial team of [Trusted Committers](../2-structured/trusted-committer.md) committed to the component. + +Expectations related to collaboration are transparent for everyone involved going forward e.g. by creating [base documentation in CONTRIBUTING.md](../2-structured/project-setup/base-documentation.md). + +The entire decision process backing the result is transparent and can be influenced by those affected, leading to higher buy-in for the final result. Also the argument leading to the final decisions are accessible for those new to the project. + +There is a proven way to adjust the setup in the future. + +# Status + +Initial (early draft) diff --git a/patterns/1-initial/good-first-project.md b/patterns/1-initial/good-first-project.md new file mode 100644 index 000000000..60331d516 --- /dev/null +++ b/patterns/1-initial/good-first-project.md @@ -0,0 +1,89 @@ +## Title + +Good First Project + +## Patlet + +An InnerSource program has been launched at an organization, and to get off to a successful start it requires some good first projects that lend themselves to InnerSource-style development. Assessing the InnerSource-readiness (fitness) of the candidate projects can help in selecting projects that have the potential to help demonstrate the power of InnerSource. + +## Problem + +When launching an InnerSource program, it is essential to convince the skeptics about the utility of InnerSource (see the [Start as Experiment](../2-structured/start-as-experiment.md) pattern). + +While any project has the potential to benefit from being developed in InnerSource style, some are more suitable candidates than others. But how do you find the projects that have the best chance to succeed as InnerSource projects? + +Moreover, while previous works focused on the criteria for readiness for InnerSource adoption at an organizational level, there seems to be no concise and actionable guideline for assessing the InnerSource-readiness for individual projects. + +## Context + +- An organization is starting or is in the early phase of InnerSource adoption, with a lot of skepticism about whether or not it'll work. +- Selecting an inappropriate pilot project might lead to failure of the entire initiative (see the [Start as Experiment](../2-structured/start-as-experiment.md) pattern). +- Otherwise, a team might be planning to start an InnerSource project but they do not know how prepared they are and if the project they are putting forward is appropriate or not. + +## Forces + +- Lack of knowledge about which projects stand to benefit the most from InnerSource development. +- The team might think they are prepared for InnerSource, but might not have an idea about what challenges lie ahead and how prepared they actually are. +- Unsure if the tools used by the project and the organizational processes are conducive to InnerSource style development. + +## Solutions + +This pattern presents a framework (_Project-Process-People_ model) and an _accompanying tool_ as one specific implementation of the framework for identifying the _fitness_ of an InnerSource project. The framework is based on prior work by [Klaas-Jan Stol and Brian Fitzgerald](https://ulir.ul.ie/bitstream/handle/10344/4443/Stol_2014_inner.pdf) and [Silona Bonewald](https://innersourcecommons.org/learn/books/understanding-the-innersource-checklist/), and helps to find promising candidate InnerSource projects by assessing their InnerSource-readiness. + +We hypothesize that the _fitness_ of a project can be measured by examining the characteristics of the project, the tools used and the organizational practices, and the readiness of the team in-charge, which we call the _Project-Process-People model_. We suggest two sub-factors within each which overall provides __six__ dimensions to measure the fitness of candidate projects. + +### List of factors to assess InnerSource Fitness + +1. __Project Compatibility__ + - _Seed Product_ -> Do the project characteristics make it suitable for InnerSource style development? + - _Multiple Potential Stakeholders_ -> Is the project likely to attract developers from different teams and build a community around the project? +2. __Process Compatibility__ + - _Appropriate Tools and Practices_ -> Do project practices facilitate contributions from outsiders and are the tools used in the project too specific and need to learned? + - _Ease of contribution_ -> Are the required ancillary resources set up and is the code modular enough to facilitate contribution? +3. __People Compatibility__ + - _Team Readiness for InnerSource_ -> Are the team members aware of and ready for the challenges of maintaining an InnerSource project? + - _Management Support_ -> Is the management willing to support the developers working on the project and the initiative in general? + +### Reference Implementation + +The [InnerSource Project Fitness Tracker](https://github.com/tapjdey/InnerSource_Project_Fitness) is one specific implementation of this pattern. It helps estimating the _fitness_ of a candidate project along the six dimensions explained above, and presents an aggregate score which is the weighted sum of the scores for these dimensions. (As an side: Weights are determined by how many people considered a characteristic important in the [InnerSource Survey 2020](https://tapjdey.github.io/InnerSource_Survey_2020/index.html)). + +This [demo video](https://imgur.com/a/wO4EyJj) shows the operation of the tool mentioned above. + +## Resulting Context + +Using the framework helps to assess the InnerSource-readiness of individual projects. + +The _fitness score_ of a project can be used as an indication about its suitability for InnerSource style development, which can help in selecting the most appropriate candidate projects. By choosing projects with higher chances of InnerSource success, you also increase the chances of the overall InnerSource program to be successful. + +The questionnaire presented in the tool also serves as a de-facto guide as to which aspects need attention for making a project better suited for InnerSource style development. + +## Rationale + +The two most important works in this context are by [Klaas-Jan Stol and Brian Fitzgerald](https://ulir.ul.ie/bitstream/handle/10344/4443/Stol_2014_inner.pdf) and [Silona Bonewald](https://innersourcecommons.org/learn/books/understanding-the-innersource-checklist/). + +In their work, _Stol and Fitzgerald_ presented a set of nine key factors that are important for organizations to consider when adopting inner source. However, that model looked at an organization as a whole, and while a number of organizational characteristics are applicable to an individual project, some aspects are not, and some project characteristics are unaccounted for in the model. They presented three main factors: Software Product, Practices and Tools, People and Management, and three sub-factors on each of them. + +_Silona Bonewald_, on the other hand, presented a near-exhaustive checklist about different aspects to consider while adopting InnerSource at an organization. However, not all of them are applicable while considering an individual project. Ideas from the two works described earlier are combined in framing the pattern presented here. + +## Known Instances + +TBD + +## Status + +* Initial + +## Author(s) + +* Tapajit Dey +* Brian Fitzgerald + +## Acknowledgements + +Willem Jiang from Huawei for the feedback on the tool and translation to Chinese. + +## Alias + +* InnerSource Project fitness +* InnerSource-Readiness of a project diff --git a/patterns/1-initial/governance-levels.md b/patterns/1-initial/governance-levels.md new file mode 100644 index 000000000..196570df6 --- /dev/null +++ b/patterns/1-initial/governance-levels.md @@ -0,0 +1,72 @@ +## Title + +Transparent Governance Levels + +## Context + +Several teams are using InnerSource patterns and best practices. However the +degree to which they welcome not only contributions but give equal collaboration +rights to contributors differ. As a result there are unmatched expectations, +confusion and frustration when teams collaborate across team boundaries. + +## Problem + +For two projects InnerSource best practices have been adopted. Project A +has a shared ownership model with [Trusted Committers](../2-structured/trusted-committer.md) from multiple teams. +Project B is fully owned by one team, only contributions are coming from +multiple teams. New contributors to either project are regularly confused about +the level of influence they can gain to the respective project. This leads to +long discussions, escalations and time lost on clarifications. + +## Forces + +- For project A shared ownership works well, members coming from multiple teams + are working together. +- For project B the backing team would like to retain a certain level of + ownership and control. Sharing ownership with other Trusted Committers outside + of the original team is not an option. +- Contributors want clarity on the level of influence they can gain in an + InnerSource project they are involved with. +- Writing detailed guidelines into each contributions file leads to a lot of + text that is hard to understand for engineers. + +## Solution + +Establish standardised building blocks which can be used by projects to signify +how much influence they are willing to share. Those building blocks can then be +used in contributing files. + +Examples of building blocks: + +* **Bug reports and issues welcome**: People outside the core development team are + welcome to read the code. They can submit feature requests and bug reports for + things they would like to see changed. + +* **Contributions welcome**: People outside the core development team may use the + code, make modifications and feed those modifications back into the projects. + Trusted committers are willing to mentor those contributions to a state where + they can be accepted or communicate clearly why the proposed change cannot be + made. + +* **Shared write access**: In addition to the above people outside the core + development team may gain write access to the source repository. Influence on + roadmap decisions as well as influence on who else gains write access is + restricted to the core development team. + +* **Shared ownership**: Members of different teams collaborate on the project as + equal peers. Everyone has the ability to merge code. Everyone has an equal say + on the project direction. Everyone has an equal say in who else to add to this + group. + +## Resulting Context + +Teams can adopt InnerSource best practices in a step-by-step way. By documenting +individual steps contributor confusion is avoided. + +## Known Instances + +TBD + +## Status + +Initial (Early draft) diff --git a/patterns/1-initial/improve-findability.md b/patterns/1-initial/improve-findability.md index 3e69930d3..bf594f7ac 100644 --- a/patterns/1-initial/improve-findability.md +++ b/patterns/1-initial/improve-findability.md @@ -2,18 +2,13 @@ Improve Findability -## Also Known As - -- Badly Named Piles -- Poor Naming Conventions - ## Patlet -TBD +People can't find the internally developed solutions that they need due to poor naming conventions. This causes frustration in finding InnerSource solutions and a reduction in code reuse. ## Problem -People can't find the internally developed solutions that they need due to poor naming conventions. +People can't find the internally developed solutions that they need due to poor naming conventions. This causes frustration in finding InnerSource solutions and a reduction in code reuse. ## Context @@ -36,14 +31,14 @@ To help improve findability for inner source projects: - Include keywords in project descriptions. - Apply tagging to repositories (validated). - Use labels where possible. -- If possible, pull repository names, descriptions, and README.md files into the search engine (not the code itself). +- If possible, pull repository names, descriptions, and `README.md` files into the search engine (not the code itself). - Instate a concierge service (guide) to help product people find stuff. (This approach might not scale, but could be helpful at the beginning of a program.) Poor naming conventions ## Known Instances -None known as of yet---this is a pattern idea until it is proven. +None known as of yet - this is a pattern idea until it is proven. ## Desired Resulting Context @@ -67,3 +62,8 @@ None known as of yet---this is a pattern idea until it is proven. - Erin Bank (CA Technologies) - Padma Sudarsan (Nokia) - Tim Yao (Nokia) + +## Also Known As + +- Badly Named Piles +- Poor Naming Conventions diff --git a/patterns/1-initial/incentive-mechanisms-for-voluntary-contribution.md b/patterns/1-initial/incentive-mechanisms-for-voluntary-contribution.md index ec42e4766..c433d35e8 100755 --- a/patterns/1-initial/incentive-mechanisms-for-voluntary-contribution.md +++ b/patterns/1-initial/incentive-mechanisms-for-voluntary-contribution.md @@ -30,7 +30,7 @@ InnerSource project. As a result, the total number of contributors remained restricted to the core team and the project cannot build a community of developers. Furthermore, contributions mostly originated -in the same business unit the Dedicated Community Leader (link to Dedicated Community Leader) +in the same business unit the [Dedicated Community Leader](../2-structured/dedicated-community-leader.md) belonged to. Innovation did not happen in the expected scale. Top management is no longer convinced that InnerSource yields the expected benefits and abandons the initiative altogether. diff --git a/patterns/1-initial/include-product-owners.md b/patterns/1-initial/include-product-owners.md new file mode 100644 index 000000000..1f0e64360 --- /dev/null +++ b/patterns/1-initial/include-product-owners.md @@ -0,0 +1,72 @@ +## Title + +Include Product Owners + +## Patlet + +Engaging and educating Product Owners about InnerSource can help them modify their actions (e.g., in the space of KPIs) to help InnerSource collaboration work better. + +## Problem + +Key Performance Indicators (KPIs) for Product Owners are primarily product focused, and don't consider areas such as collaborative development. This results in a lower level of engagement with InnerSource projects. + +## Forces + +* KPIs discourage Developers from contributing to others via InnerSource. +* Product Owners have different priorities that may not align directly with InnerSource priorities. Product Owners are focused on their ROI in alignment with Product Management. +* Product Owners may not be as focused on the longer-term benefits of InnerSource because many of their own metrics and goals are shorter lived. +* Product Owners may not be aware of the benefits of InnerSource +* Employees desire to grow their own circle of influence, which leads them to limited sharing of their own resources. +* Some people lack understanding of the up-front impact and cost of InnerSource in terms of resources, because they are more focused on the efficiencies that it can provide. +* Product Owners might not use Development tools and may therefore lack the opportunity to find out about InnerSource offerings and opportunities for collaboration and reuse. +* Fear of loss of control. +* Resistance to allow people to join and contribute. +* Motivation: For the receiving Product Owners, there are big benefits of external contributions. +* Motivation: Some are motivated to contribute because it is the only way that their desired feature will make it into the codebase. +* Lack of motivation: If Developers don't see what's in it for them to contribute, they might not be highly motivated to help. + +## Context + +* Teams and individuals are not rewarded for software component reuse. +* Motivations of the product(s) are not aligned with the InnerSource initiative. +* Every product area has their own limited resource/budget. +* Delivery deadlines are not movable. +* Product Owners rarely make compromises regarding technical items in their area. +* InnerSource changes resource distribution and requires up-front discussions, which require time allocation. + +## Solution + +* Talk with the Product Owners to understand their priorities. Prepare for this discussion by understanding their user stories, backlog, and roadmap if possible. +* Ensure that Product Owners are aware of the benefits of InnerSource that they might care about most, including: + - Reuse. Teams can avoid writing new software from scratch because they can leverage and/or existing code. + - Savings of time and money. It may cost more for a team other than the original team to write it, but it costs less than writing it from scratch. + - Staff augmentation for the receiving team. +* Change the collaboration model on the product side. Bring the impacted Product Owners together to discuss the InnerSource project and choices related to resource allocation. Technical collaboration will result in better quality decisions. Overall resources cost could be lowered for some areas. Having the conversation builds trust and may result in evolution of the software component. +* If possible, implement effective enterprise search. +* Adjust KPIs to motivate people to collaborate and reuse. Work with leadership to get support. +* Internally advertise opportunities for reuse and collaboration. This can be done with blogs, success stories, providing a searchable list of projects to work with, and other methods. +* Create a champions program and have them identify project opportunities. + +## Resulting Context + +* Initial time investment is rewarded by the outcomes. +* Product managers are now collaborating with one another. +* Resulting development costs less overall. +* Product owner KPIs might not change but reuse collaboration still occurs (a faster way to achieve them). +* Product owners factor in InnerSource so they reach their KPIs more efficiently. + +## Known Instances + +* PayPal is looking into finding a search solution for their project Agora. They are collaborating with other teams pursuing a similar mission, eliminating redundancy and inefficiency regarding effort and tools. + +## Status + +* Initial +* Created at the Spring Summit 2017 in Geneva, Switzerland + +## Authors + +* Silona Bonewald +* Alex Bozic, Bloomberg +* Erin Bank +* Tim Yao diff --git a/patterns/1-initial/innersource-guidance-group.md b/patterns/1-initial/innersource-guidance-group.md new file mode 100644 index 000000000..624636aba --- /dev/null +++ b/patterns/1-initial/innersource-guidance-group.md @@ -0,0 +1,61 @@ +## Title + +InnerSource Guidance Group + +## Patlet + +A highly divergent set of development standards in different teams can slow down collaboration betweens these teams. A InnerSource Guidance Group that establishes broad governance and behavioral guidelines can help to reduce these frictions. + +## Problem + +Without a set of organizational standards, [Trusted Committers](../2-structured/trusted-committer.md), and individual teams, are free to set their own standards, which is a step in the right direction. + +However, team standards could be highly variant and further diverge over time as they evolve and adapt to new needs and forces. This can lead to confusion and frustration as contributors submit code across team and functional boundaries. + +The business is interested in establishing a set of agreed-upon standard operating procedures that guide teams, while still providing sufficient autonomy to meet the parochial needs of individual teams. + +## Context + +A company is planning to introduce InnerSource as a strategic initiative. They are faced with reforming and steering the behavior of developers and engineers toward a common goal. In general functional groups and teams within the company adhere to a broad spectrum of standards regarding tools, development languages, collaboration models, engagement models, documentation models, etc. + +The company recognizes the value of the Trusted Committer role as a situational leader for a team that sets and enforces team standards, code contribution standards, contribution agreements, PR management, etc. however the company is interested in establishing organizational guidelines as well that steer and focus Trusted Committers and the teams they represent. + +As an example, the breadth of languages used within an engineering and operations organization could include, powershell, bash shell, perl, tcl, python, golang, java, shell augmented with sed and awk and jq, etc. and the organization wants to standardize as much as possible on a subset of these languages so that the ability to collaborate between teams is maximized. + +## Forces + +- Separate engineering and development teams establish development standards that may be highly divergent from other teams. (Effect: This limits the ability to collaborate.) +- People move between teams, and responsibility for specific initiatives change over time. (Effect: The ability of the organization to adapt to variant team norms results in decreased development velocity.) + +## Solutions + +Recognize that Trusted Committers are both **situational leaders** and **subject matter experts** representing their team. Establish an InnerSource Guidance Group as a “committee” attended and chaired by Trusted Committers. Charter this InnerSource Guidance Group with establishing company and/or organizational guidelines. + +- The “committee” is scheduled periodically as necessary by the Trusted Committers – twice a week, once a month, quarterly, etc. +- The goal is to establish general direction, or a highway, while leaving freedom for individual teams to adapt to local needs, or side streets +- Trusted Committers establish organization guidelines that become templates for [Contribution Agreements](../2-structured/project-setup/base-documentation.md) +- Trusted Committers collaborate on and refine guidelines asynchronously via passive documentation and the establishment of organizational patterns. + - This guideline definition project itself can be run as an InnerSource project, accepting contributions from anywhere in the organization. + - By running this as a collaborative documentation project, it can role-model and verify the behaviors that they want to promote for other InnerSource projects as well. +- The InnerSource Guidance Group is responsible for communicating general guidelines to upper management +- This also ensures that teams and functional groups have a recurring touchpoint with other team and functional groups – establishing trust and insight into the overall organizational needs and requirements + +## Resulting Context + +TBD + +## Known Instances + +- A large, highly regulated, financial organization is planning to implement a TC Steering Group to provide broad guidelines and guard rails as part of their InnerSource initiative. + +## Rationale + +Empowering Trusted Committers as representatives on behalf of their teams propagates ownership of the overall InnerSource strategy as it deploys and evolves in an organization and ensures that a baseline level of governance and standardization occurs. + +## Author(s) + +- Tim Tyler + +## Acknowledgements + +- Tim Yao diff --git a/patterns/1-initial/innersource-portal-hygiene.md b/patterns/1-initial/innersource-portal-hygiene.md index 9aef38238..97656ca3b 100644 --- a/patterns/1-initial/innersource-portal-hygiene.md +++ b/patterns/1-initial/innersource-portal-hygiene.md @@ -69,6 +69,5 @@ The automatically managed InnerSource portal and badge system has ensured that t ## Status -**Initial** - -Based of PR [#120](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/120) we decided to merge this pattern in a relatively early state, as the upstream had disappeared and we didn't want to loose the content. See further discussions in the PR itself. +* Initial +* Based of PR [#120](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/120) we decided to merge this pattern in a relatively early state, as the upstream had disappeared and we didn't want to loose the content. See further discussions in the PR itself. diff --git a/patterns/1-initial/introducing-metrics-in-innersource.md b/patterns/1-initial/introducing-metrics-in-innersource.md index 757c963e6..a9ee1bda5 100644 --- a/patterns/1-initial/introducing-metrics-in-innersource.md +++ b/patterns/1-initial/introducing-metrics-in-innersource.md @@ -56,7 +56,7 @@ Consider a third party that is seen as a neutral player to produce such metrics. Have specific training on the topic of metrics and good practices to use them. An example is to have a methodology to follow metrics such as the Goal-Question-Metric approach or the Objectives-KeyResults one. On the other hand, try to reflect the short-term and medium-term goals in the metrics to be used. -Metrics when published or discussed should be done so in the aggregate without refering to specific people. +Metrics when published or discussed should be done so in the aggregate without referring to specific people. Produce a characterization of metrics as this might be helpful for others to understand and follow. @@ -70,13 +70,15 @@ Note: The aforementioned metrics are some common examples. They aren't a one-siz The organization builds a monitoring and reporting infrastructure for the metrics that flow directly from its business goals. -Those metrics will provide visibility into the current situation of the project to the C-level executives. By comparing the metric measurements before applying inner source and to the metric measurements after applying the inner source initiative, it is possible to guage the effectiveness of the inner source initiave. +Those metrics will provide visibility into the current situation of the project to the C-level executives. By comparing the metric measurements before applying InnerSource and to the metric measurements after applying the InnerSource initiative, it is possible to gauge the effectiveness of the InnerSource initiative. Continued monitoring of these metrics will help middle management and developers understand how the initiative evolves and will help them with their daily work. ## Known Instances -## State +TBD + +## Status Initial diff --git a/patterns/1-initial/junkyard-styled-innersourcing.md b/patterns/1-initial/junkyard-styled-innersourcing.md index 556ab97c4..6042dd90a 100644 --- a/patterns/1-initial/junkyard-styled-innersourcing.md +++ b/patterns/1-initial/junkyard-styled-innersourcing.md @@ -12,7 +12,7 @@ TBD Two situations: * SW component not designed for reuse because the schedule was too tight and did not allow for the extra effort needed -* Did not have the knowledge or training to create components that can b reused. +* Did not have the knowledge or training to create components that can be reused. ## Problem @@ -35,8 +35,7 @@ Two situations: ## Status -* Initial -* Brainstormed pattern idea in progress +* Initial (brainstormed solution) ## Authors diff --git a/patterns/1-initial/modular-code.md b/patterns/1-initial/modular-code.md index 5d2a4f3e5..ee581a11f 100644 --- a/patterns/1-initial/modular-code.md +++ b/patterns/1-initial/modular-code.md @@ -23,34 +23,50 @@ Development does not want to spend the extra resources needed to develop modular * There is a learning curve to writing code that can be reused. * Extra documentation is required for reusable code. * Some companies have a common components group that develops reusable code, but others feel that such components should be developed by those business lines that are using the components and a library of common components could be established. -* Developers might not know how to write modular code. Education might be needed. +* Developers might not know how to write modular code. + * Might be a fear that if not done properly, quality might be impacted. -* Developers might not have incentive to write modular code (due to their tight schedules and lack of a mandate). +* Developers might have no incentive to write modular code (due to their tight schedules and lack of a mandate). +* If there is frequent turnover of team members, modularization may not be a priority. * You might be dealing with legacy systems (can't be simply refactored or rewritten). * Requirements might be different for writing modular code. * Architectural constraints might impact modularity. * Developers who develop monolithic code bases might lack the perspective of how modularity might improve how they work. +* Level of communication between teams can impact ability/inclination to modularize. ## Solutions * Provide incentives to teams to invest in modular code. Modular code is far more reusable. This could work well for large teams when working on modularized projects; team members can focus on their smaller assigned tasks. - Developers could get an opportunity to increase their influence in the organization. + - Modular code makes the pathway to open source smoother. + - Modular code facilitates division of labour (as required for work in larger teams, or as an Open Source project) + - Modular projects enable team members to focus on their own smaller assigned tasks. + - Modular code makes Agile implementation easier. + - Modular efforts increase autonomy and accountability for Engineers, which can raise satisfaction and quality. * Select certain "success projects," teams that will develop reusable code and demonstrate the long term success. This can help motivate others (they see what is possible and what is in it for them). Transparency is critical. * Offer education. Modular code is well-understood; there is a lot of literature in favor of this. -* Accept the cost of modularization, build time into the release schedule. +* Acknowledge and drive acceptance for the cost of modularization. Build time into the release schedule for this. * Companies moving to use more open source code will appreciate modularity more over time. -* Modular code is easier to work with, especially for larger teams. * Mitigate risk and fear of quality degradation from accepting InnerSource contributions. * Establish a checklist of elements to be checked off to classify a component as reusable. - There could be requirements on tests, tools and documentation before considering a component as reusable + - Introduce refactoring as organic effort and strive for it to become part of the culture. Refactoring leads to more modular code and reduction of technical debt. * Establish standards on testing methodology, labeling of repos. ## Resulting Context -Time is spent making the shared code modular so it can be reused. +**Pattern Idea**: Time is spent making the shared code modular so it can be reused. + +## Known Instances + +Elements of the resolution have been proven by various companies. ## Status Initial -## Author +## Authors + +* Tim Yao, Nokia +* Erin Bank, CA Technologies +* Keerthi Surapaneni diff --git a/patterns/1-initial/open-source-trumps-innersource.md b/patterns/1-initial/open-source-trumps-innersource.md new file mode 100644 index 000000000..25c2d39c3 --- /dev/null +++ b/patterns/1-initial/open-source-trumps-innersource.md @@ -0,0 +1,68 @@ +## Title + +Open Source trumps InnerSource + +## Patlet + +Developers disregard InnerSource projects because they consider open source projects to be superior. Introducing a required evaluation of InnerSource projects before choosing an open source project increases the likelihood of the InnerSource projects to be adopted. + +## Problem + +People find the InnerSource project but, even if the InnerSource component meets their needs better than the respective open source component, they choose the open source component over the InnerSource component. + +## Context + +* People look for software through external search engines. +* Different Business Lines (BLs) are selecting different SW components to do the same function, resulting in inconsistencies in the user experience. +* There may be many silos in the company; it would then be difficult to reach the developer base across those silos. +* The company culture is based on strong governance. + +## Forces + +* There is a perception that the open source components are of higher quality and more reusable than the InnerSource components. This is caused by the common belief that open source always means many more developers and users and therefore higher quality. This is sometimes the case in open source but not always! +* The channels to get needed changes done are more established with open source (GitHub) than with internal components (GitHub Enterprise, Bitbucket, GitLab, Gerrit - possibly multiple installations in one company). +* Open source should be voluntary; mandating people to use internally developed software goes against open source principles. +* Internally developed components are potentially more suitable for corporate use if they are designed with that in mind. +* Using corporate licensed InnerSource components instead of using open source components with strong copyleft license avoids having to disclose IP +* It can be hard to find relevant projects in GitHub (especially if names are cryptic and keywords aren't used). See [Poor Naming Conventions](https://github.com/paypal/InnerSourcePatterns/pull/59). +* The consistent use of internally developed components potentially reduces the diversity of the internal software landscape compared to a situation where every business line chooses their own, favourite open source component. + +## Sketch + +![The landscape of effective and efficient software development](/assets/img/landscape-of-effective-and-efficient-software-development.png "The landscape of effective and efficient software development") + +**Source:** [Commodification of Industrial Software: A Case for Open Source](https://www.semanticscholar.org/paper/Commodification-of-Industrial-Software%3A-A-Case-for-Linden-Lundell/54d6cb77a86e292ff1845eb910c1a1f258e6cee3), F. Linden, B. Lundell, P. Marttiin, Published 2009, Engineering, Computer Science, IEEE Software + +## Solutions + +* Corporate governance mandates that internally developed components are to be evaluated before open source component are selected. +* Make it easier to find relevant InnerSource components (see [InnerSource Portal](../2-structured/innersource-portal.md)). +* Assign maintainers to make sure proper open source processes are being followed within the leading repos. +* Increase the attractiveness of InnerSource components by providing “value add” services for them, such as automated CI/CD services, IaaS/PaaS, NPM organization/server linkages, ChatOps, etc. + +## Resulting Context + +* Developers select the best component regardless of whether it is open source or internally developed (InnerSource). They do so with full knowledge of the InnerSource component, its capabilities, and reasons why it is recommended. +* By doing so, InnerSource components end up being more widely and consistently used within the company. + +## Known Instances + +TBD + +## Status + +Initial + +## Author + +* As told to Padma Sudarsan, 2016-09-30 +* Tim Yao +* Georg Gruetter (Robert Bosch GmbH) +* Russ Rutledge +* Johannes Tigges +* Sebastian Spier + +## References + +* Some interesting conversation threads from the time when this pattern was created can be found in [this PR](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/46/). +* [Commodification of Industrial Software: A Case for Open Source](https://www.semanticscholar.org/paper/Commodification-of-Industrial-Software%3A-A-Case-for-Linden-Lundell/54d6cb77a86e292ff1845eb910c1a1f258e6cee3), F. Linden, B. Lundell, P. Marttiin, Published 2009, Engineering, Computer Science, IEEE Software diff --git a/patterns/1-initial/organizational-mindset-change.md b/patterns/1-initial/organizational-mindset-change.md index 8e96f940c..85d7b88ff 100644 --- a/patterns/1-initial/organizational-mindset-change.md +++ b/patterns/1-initial/organizational-mindset-change.md @@ -32,6 +32,4 @@ All of the company heartily adopts inner sourcing! Cake for everyone! ## Status -Donut - -## Author(s) +* Initial (Donut) diff --git a/patterns/1-initial/release-process.md b/patterns/1-initial/release-process.md new file mode 100644 index 000000000..e98a02f8a --- /dev/null +++ b/patterns/1-initial/release-process.md @@ -0,0 +1,51 @@ +## Title + +Standard Release Process and Published Artifacts + +## Patlet + +Teams may be reluctant to use InnerSource projects that they are unfamiliar with when there is no clear release process apparent in the repository. +Providing clear release notes and a published artifact (binary, docker image, jar, etc) gives people confidence you are publishing a quality product. + +## Problem + +When a team is deciding whether or not to use an InnerSource projects, one of their considerations is whether they trust that they can rely on the given project for an extended period. Switching the tools/projects that they are using has a cost, so they only want to make those investments sporadically. + +It reduces trust if the given InnerSource projects doesn't have a published artifact or publicly viewable release process, as the team won't know when they can expect new features or the next release, how breaking changes are handled, etc. + +## Context + +It is common practice in Open Source projects to have releases, with release notes documenting breaking changes, +new features, etc along with either a published binary or link to a Docker image. This practice may not be as +transparent or well documented/visible for InnerSource projects, modules, etc. Providing robust release notes +along with a published artifact that is the result of a clearly documented and visible release process builds trust and confidence in your project. + +## Forces + +- Difficult for organizations that don't have a central CI/CD system +- Adds the burden of publishing release notes +- Becomes more difficult if the organization does not provide an internal location to host artifacts + +## Solution + +- CI/Delivery Pipeline is located within your repo to build artifacts (binary, docker image, jar, etc) +- Releases and accompanying build artifacts are generated by CI system at build time +- Release includes notes on New Features, Bug Fixes, and any "Breaking Changes" specifically called out + +A good example of quality Release notes can be found [here](https://github.com/jaegertracing/jaeger/releases) + +## Resulting Context + +Teams who come across your project will see published release notes and gain confidence in your tool. Published artifacts also make using your product easier and quicker to adopt. Having well-defined and visible processes such as these also help with cross-team collaboration and new contributors. Folks can be confident that their contributions are made available and distributed in a reasonable amount of time with a clear usage path. + +## Known Instances + +Comcast + +## Authors + +David Grizzanti + +## Status + +**Initial** - FYI we are considering splitting "Published Artifacts" into its own pattern diff --git a/patterns/1-initial/reluctance-to-accept-contributions.md b/patterns/1-initial/reluctance-to-accept-contributions.md index be54e9193..2868bce14 100644 --- a/patterns/1-initial/reluctance-to-accept-contributions.md +++ b/patterns/1-initial/reluctance-to-accept-contributions.md @@ -51,8 +51,9 @@ The last 3 patterns above were mentioned to be "under construction" at the time ## Status -11 Oct 2016 - First draft -13 Apr - Reviewed & Revised +* Initial +* 11 Oct 2016 - First draft +* 13 Apr - Reviewed & Revised ## Author diff --git a/patterns/1-initial/share-your-code-to-get-more-done.md b/patterns/1-initial/share-your-code-to-get-more-done.md index 4cfb465d5..a5a3419b1 100644 --- a/patterns/1-initial/share-your-code-to-get-more-done.md +++ b/patterns/1-initial/share-your-code-to-get-more-done.md @@ -2,8 +2,6 @@ Share Your Code to Get More Done -Old title: Share Your Code to Get More Done - Likely Contributors Variant - ## Patlet TBD @@ -46,9 +44,9 @@ TBD * People from outside the traditional silo are contributing successfully * More development is getting done per period (sprint) -## Rationale (optional) +## Known Instances -## Known instances (optional) +TBD ## Status @@ -59,3 +57,7 @@ TBD ## Author David Marcucci + +## Alias + +Old title: Share Your Code to Get More Done - Likely Contributors Variant diff --git a/patterns/1-initial/shared-code-repo-different-from-build-repo.md b/patterns/1-initial/shared-code-repo-different-from-build-repo.md index 4925dca28..9dc473520 100644 --- a/patterns/1-initial/shared-code-repo-different-from-build-repo.md +++ b/patterns/1-initial/shared-code-repo-different-from-build-repo.md @@ -28,8 +28,8 @@ Ideally, overhead is minimized or eliminated. Or integrate the shared code repos ## Known Instances -## Status +TBD -Unproven +## Status -## Author +Initial diff --git a/patterns/1-initial/source-code-inventory.md b/patterns/1-initial/source-code-inventory.md new file mode 100644 index 000000000..8710ad78b --- /dev/null +++ b/patterns/1-initial/source-code-inventory.md @@ -0,0 +1,110 @@ +## Title + +Unified Source Code Inventory + +## Patlet + +In a large organization with different legal entities is often hard to get full visibility into all software assets, in particular all source code. This situation reduces the opportunities to increase business value and keep liability costs, such as software maintenance, under control across the organization as a whole. An organization-level source code inventory addresses these issues while exploiting opportunities to identify and support valuable InnerSource assets. + +## Problem + +Given situations when InnerSource stakeholders do not value source code at the same level as other organization's assets; when source code strategies are ad-hoc and different among legal entities with little consolidation at organization-level; then it becomes harder both to select and support the right InnerSource project candidates as well as maximize business value of such a key asset. + +Can you get consistent answers within the organization to questions like? + +* How would you find all source code touched by anyone in your legal entity? +* How would you find out who else can also access each of the above? +* For new source code, what is your default level of access? +* How would you know nothing is missing from your inventory? +* What valuable insights or actions have you gained from your inventory? + +## Context + +* You work on Legal Entity within a complex Organization under continuous change (e.g., new acquisitions or changing business priorities). +* You cannot find all source code touched, shared and consumed within the Organization. +* You do not have a clear policy on default sharing level when creating a new project (e.g., Open Source, InnerSource or Closed Source). +* You cannot scan significant parts of the Organization's source code looking for duplication, similarity or code smells. +* You do not know the existing ratios of Open Source, innerSource and Closed Source and their trend. +* You cannot measure the diversity of contributions and resulting value for a given project. +* You cannot identify and optimize tech stack diversity. +* You cannot identify technical debt and determine the priorities for retirement (e.g., dead APIs/source). + +## Forces + +* Fragmentation of source code hosting systems in the organization. +* Ad-hoc source code strategies scattered across the different Legal Entities in the organization. +* Continuously changing map of the relationships between: projects, repositories, products, tech stacks, domains, solutions, platforms, services, components, sub-systems, people, authors, teams, external repositories. +* Diverse software culture of teams across the organization (e.g., more open to collaboration or more siloed). + +## Solutions + +### Set up an organization-level source code inventory live dashboard + +* Combination of manual and automated input data sources to a single source of truth +* API available to add new data sources and extend coverage of the source code repository +* Key meta-data about each repository: + * Legal Entity + * URL + * Version control system (e.g., GIT or SVN). + * Hosting vendor (e.g., GitHub, Gitlab or BitBucket) and hosting type (e.g., on-prem, private cloud or public cloud). + * Sharing level (e.g., Open Source, InnerSource, Closed Source). +* Visualization in place to list all assets with options to filter based on meta-data +* Enable access to automated source code static analysis tools (e.g., identify duplicated or similar code, flag code smells, benchmark test coverage). + +Mockup dashboard | Mockup questionnaire +:-------------------------:|:-------------------------: +![Mockup dashboard](../../assets/img/source-code-inventory-mockup-dashboard.PNG) | ![Mockup questionnaire](../../assets/img/source-code-inventory-mockup-questionnaire.PNG) + +### Define a Source Code Strategy Assessment Framework + +* Help to define a source code strategy including an explicit definition of policies at Organization and Legal Entity levels for: + * Inventory + * Sharing + * Consumption + * Contribution + * Ecosystem +* Example of such a framework: [github.com/trieshard/source-strategy-assessment/blob/master/framework.md](https://github.com/trieshard/source-strategy-assessment/blob/master/framework.md) + +## Resulting Context + +### For the Organization, Legal Entity and Project maintainers + +* We have explicit policies at Organization and Legal Entity level on source code strategy (e.g., where to create new repository or how to select the right sharing level). +* We can find all source code touched, shared and consumed within the Organization or Legal Entity and take actions as needed. +* We can measure the diversity of contributions and resulting business value for our project. +* We can identify technical debt and determine the priorities for retirement (e.g., dead APIs/source). + +### For InnerSource governance + +* We can scan significant parts of our Organization's source code looking for opportunities of reuse, duplication, similarity or code smells. +* We know the ratios of Open Source, InnerSource and Closed Source within the Organization so we can steer as needed. +* We can identify and optimize tech stack diversity. +* We can create awareness and culture shift on certain Legal Entities as needed (e.g., ratio of Open Source and InnerSource below average). + +## Rationale + +It creates a dynamic and extendable single source of truth for repositories to capture, visualize and act on source code repositories across the Organization. That helps to create awareness and focus efforts on the right direction. The Source Code Strategy Assessment Framework helps teams to understand the value of intentional explicit policies on how to manage source code. It helps to create both continuous improvement cycles and references within the Organization of what others are doing. + +## Known Instances + +This is under test at scale at: + +* Philips + +## References + +* Organization and Legal Entity terms as defined in [InnerSource License Pattern Glossary](../2-structured/innersource-license.md#glossary). +* Explore using this pattern in combination with the [InnerSource Portal](../2-structured/innersource-portal.md) pattern. + +## Status + +* Initial + +## Author(s) + +* [David Terol](https://github.com/dterol23) +* [Simao Williams](mailto://me@simaos.net) + +## Acknowledgements + +* [Sebastian Spier](https://github.com/spier) diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md index c264d4527..dcea720f3 100644 --- a/patterns/2-structured/30-day-warranty.md +++ b/patterns/2-structured/30-day-warranty.md @@ -12,50 +12,35 @@ A team develops a component which is used throughout an organization. This team ## Context -Teams depend on another team accepting their contributions so that a component produced by the receiving team can be used by the contributing team. The receiving team does not have the resources, knowledge, permission, and/or inclination to write the contributed component. - -- TBD: link to pattern "setting clear expectations for contributing code" +- Teams depend on another team accepting their contributions so that a component produced by the receiving team can be used by the contributing team. +- The receiving team does not have the resources, knowledge, permission, and/or inclination to write the contributed component/feature themselves. ## Forces -- There is distrust of contributions due to a past history of cheating: teams - submitted half finished contributions and subsequently filed requests for - fixes that make it ready for use in production. -- If code is contributed from outside the team, the team has the natural - suspicion that the other team does not know how to write code that would - meet the teams expectations. -- Each team looks first to help its own leaders achieve their own goals. This direction - of loyalty can complicate resolution of this problem. -- There is a natural aversion to taking responsibility for code not written - by oneself. -- Contributed needs to be heavily rewritten before being accepted into the - codebase. -- There is the fear of the contributors not being available for support with - fixing bugs after the time on contribution. -- Teams fear contributed code will lead to high(er) maintenance costs but do - not know how to control for that. -- Receiving teams may fear that teaching others how to contribute code will - expose technical debt in their system and that visibility may be damaging. -- Receiving teams may not believe that they will get acceptable code no - matter how much mentoring they provide. -- Either team may not feel confident in measuring risks or certifying that - they are mitigated in a contribution; the system itself is somewhat brittle - (may not be ways to fully test and catch all problems). +- There is distrust of contributions due to a past history of cheating: teams submitted half finished contributions and subsequently filed requests for fixes that make it ready for use in production. +- If code is contributed from outside the team, the team has the natural suspicion that the other team does not know how to write code that would meet the teams expectations. +- Each team looks first to help its own leaders achieve their own goals. This direction of loyalty can complicate resolution of this problem. +- There is a natural aversion to taking responsibility for code not written by oneself. +- Contributed needs to be heavily rewritten before being accepted into the codebase. +- There is the fear of the contributors not being available for support with fixing bugs after the time on contribution. +- Teams fear contributed code will lead to high(er) maintenance costs but do not know how to control for that. +- Receiving teams may fear that teaching others how to contribute code will expose technical debt in their system and that visibility may be damaging. +- Receiving teams may not believe that they will get acceptable code no matter how much mentoring they provide. +- Either team may not feel confident in measuring risks or certifying that they are mitigated in a contribution; the system itself is somewhat brittle (may not be ways to fully test and catch all problems). ## Solution -Address the fears of both the receiving and the contributing teams by establishing a 30 day period starting with the time the contributed code goes into production, during which the contributing team consents to provide bug fixes to the receiving team. - -Provide clear contribution guidelines spelling out the expectations of the receiving team and the contributing team. +Address the fears of both the receiving and the contributing teams by establishing a **30 day warranty period** starting with the time the contributed code goes into production. During this warranty period the contributing team consents to provide bug fixes to the receiving team. 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. + 30 Day Warranty ## Resulting Context -- The receiving team is willing to accept contributions and able to share the - workload of initial adaptations/fixes. +- The receiving team is willing to accept contributions and able to share the workload of initial adaptations/fixes. - Increased transparency and fairness. - Keeps escalations from becoming too heavyweight. @@ -77,10 +62,8 @@ This was tried and proven successful at PayPal. ## Status * Structured -* Old status: Proven * Drafted at the 2017 Spring InnerSource Summit; reviewed 18 July 2017. ## Variants -- Ensure cooperation of dependent teams by making them a community by having - more than one, meritocratically appointed "[Trusted Committers](./trusted-committer.md)" (TCs) take responsibility. +- Ensure cooperation of dependent teams by making them a community by having more than one, meritocratically appointed "[Trusted Committers](./trusted-committer.md)" (TCs) take responsibility. diff --git a/patterns/2-structured/common-requirements.md b/patterns/2-structured/common-requirements.md index 064cc1090..79ff10b66 100644 --- a/patterns/2-structured/common-requirements.md +++ b/patterns/2-structured/common-requirements.md @@ -41,10 +41,11 @@ In the example presented above, the supplier helps both customers realize that t This might require negotiating requirements changes with the customer. The changes might also require involvement by the sales teams and product managers to get alignment on the requirements. The customer might need incentives, such as discounts, to agree to the changes. -A related pattern (to be written) is a circular story-writing exercise reported at one company employing Inner Sourcing. -The developers write a story to solve a problem in one way. +A related pattern [pattern to be written] is a circular story-writing exercise reported at one company employing InnerSource. -The program managers rewrite the story to better express their needs---keeping the essence the same. By the time it returns to developers though they don't recognize it as what they wanted to do in the first place and so balk at implementing it. The solution to this pattern is to have more seats around the planning table so that story modifications are understood across the project not just in the developer or program manager camps. +* The developers write a story to solve a problem in one way. +* The program managers rewrite the story to better express their needs - keeping the essence the same. By the time it returns to developers though they don't recognize it as what they wanted to do in the first place and so balk at implementing it. +* The solution to this pattern is to have more seats around the planning table so that story modifications are understood across the project not just in the developer or program manager camps. ## Known Instances @@ -53,8 +54,8 @@ TBD ## Status * Structured -* Old status: Proven +* Drafted Aug 2016 ## Author -Robert Hanmer, 22 Aug 2016, 20 Sept 2016 +Robert Hanmer diff --git a/patterns/2-structured/contracted-contributor.md b/patterns/2-structured/contracted-contributor.md index 3e06a8464..8b37b2441 100644 --- a/patterns/2-structured/contracted-contributor.md +++ b/patterns/2-structured/contracted-contributor.md @@ -10,15 +10,15 @@ Associates wanting to contribute to InnerSource are discouraged from doing so by Without support by middle management, the total number of contributors and, as a result, the amount of contributions made and value generated by the -InnerSource initiative will likely fall below expectation of top level +InnerSource initiative will likely fall below expectation of top-level management. This will likely be amplified if there is no adequate funding for and empowerment of [Dedicated Community Leaders](dedicated-community-leader.md). -This runs the risk of top level management abandoning the InnerSource idea. +This runs the risk of top-level management abandoning the InnerSource idea. ## Context A large corporation has started an InnerSource initiative. Major goals for the -initiative are to increase the efficiency of distributed software develoment +initiative are to increase the efficiency of distributed software development and to foster innovation by allowing every associate to voluntarily contribute to InnerSource projects, regardless of topic and business unit. @@ -27,12 +27,11 @@ them, the InnerSource initiative is just one of many initiatives to foster innovation and efficiency, though. They are funding InnerSource with money and capacity for community leaders and are largely giving autonomy as for how the budget is spent. They are also limiting the breadth and duration of the -initiative and partake in periodic reviews until there is proof that it yields +initiative and partake in periodic reviews until there is proof it yields the expected results (see [Review Committee](review-committee.md)). Top level -management has announced their support for InnerSource on various company -internal meetings. +management has announced their support for InnerSource on various company-internal meetings. -However, top level management has not yet empowered or incentivised mid-level +However, top-level management has not yet empowered or incentivised mid-level managers to allow or even motivate their employees to participate in cross-divisional InnerSource activities. In addition to that, the capacity of every associate is usually allocated to non InnerSource projects for 100 % of @@ -43,29 +42,13 @@ hours, not during free time. ## Forces -- Managers are held responsible for the results of their business units. - Letting their staff participate in InnerSource activities which might spend - time making contributions outside of their business unit effectively reduces - the capacity of his or her unit. This will likely make it harder for the - managers to reach or exceed their goals. -- Line managers and HR will, by default, judge the performance of their - subordinates against their business units goals, which might not be aligned - with the goals of the InnerSource community. -- The less executive air cover a line manager perceives he has, the less likely - is he or she to have his or her staff participate in InnerSource activities - which contribute to another business unit. -- The less transparency and control a line manager has of work done by one of - her subordinates, the less likely is she to allow her to contribute. -- The less formally work in InnerSource is managed and organised, the less - likely a line manager who is accustomed to formal processes is to sign off on - one of her employees contributing to InnerSource. -- The more time an associate spends on contributions to an InnerSource project - which does not benefit his day-to-day work, the more will the workload for - his teammates in his business unit increase. -- Individual contributors will likely consider participating in InnerSource - as an opportunity to enhance their professional network within the company - and to gain knowledege and experience in the technical area of her - contributions. +- Managers are held responsible for the results of their business units. Letting their staff participate in InnerSource activities which might spend time making contributions outside of their business unit effectively reduces the capacity of his or her unit. This will likely make it harder for the managers to reach or exceed their goals. +- Line managers and HR will, by default, judge the performance of their subordinates against their business units goals, which might not be aligned with the goals of the InnerSource community. +- The less executive air cover a line manager perceives he has, the less likely is he or she to have his or her staff participate in InnerSource activities which contribute to another business unit. +- The less transparency and control a line manager has of work done by one of her subordinates, the less likely is she to allow her to contribute. +- The less formally work in InnerSource is managed and organised, the less likely a line manager who is accustomed to formal processes is to sign off on one of her employees contributing to InnerSource. +- The more time an associate spends on contributions to an InnerSource project which does not benefit his day-to-day work, the more will the workload for his teammates in his business unit increase. +- Individual contributors will likely consider participating in InnerSource as an opportunity to enhance their professional network within the company and to gain knowledge and experience in the technical area of her contributions. ## Solution @@ -74,21 +57,12 @@ centrally funded and steered InnerSource governance office (ISGO). Have the ISGO reimburse business units who contracted contributors for the contracted time. -- The contracting specifies a maximum percentage of the associates work time in - InnerSource. -- The contracting clearly states that work in the contributor's business unit - takes precendence over work in InnerSource. -- The contracting states that it is not required to work in InnerSource for the - maximum percentage specified in the contract. -- The contracting is signed by the contributor, the contributor's line manager, - the governance office and the [Dedicated Community - Leader](dedicated-community-leader.md) of the community the contributor will - be contributing to. -- The governance office offers to mediate between the contributor and her line - manager in case of conflict regarding the time for contributions. -- The [Dedicated Community Leader](dedicated-community-leader.md) participates - in or provides input for performance reviews of contributors contracted for - more than 20 %. +- The contracting specifies a maximum percentage of the associates work time in InnerSource. +- The contracting clearly states that work in the contributor's business unit takes precedence over work in InnerSource. +- The contracting states that it is not required to work in InnerSource for the maximum percentage specified in the contract. +- The contracting is signed by the contributor, the contributor's line manager, the governance office and the [Dedicated Community Leader](dedicated-community-leader.md) of the community the contributor will be contributing to. +- The governance office offers to mediate between the contributor and her line manager in case of conflict regarding the time for contributions. +- The [Dedicated Community Leader](dedicated-community-leader.md) participates in or provides input for performance reviews of contributors contracted for more than 20 %. Contracted Contributor @@ -98,33 +72,22 @@ A formal contracting and centrally funded reimbursements convincingly communicating the organizations support for the InnerSource initiative, thus empowering middle management to sign off on it: -- Allocation of corporate funds to business units for reimbursement of - development capacity signals to line managers that InnerSource is deemed - valuable by the organization, that it has executive air cover and that they - are expected to support it, too. -- A formal contracting signals that work in InnerSource is managed - professionally and inspires trust. -- A formal contracting increases transparency and provides a better overview - about the associate's available capacity for his business unit and - InnerSource projects, thus reducing the risk of "over-booked/planned - capacity". +- Allocation of corporate funds to business units for reimbursement of development capacity signals to line managers that InnerSource is deemed valuable by the organization, that it has executive air cover and that they are expected to support it, too. +- A formal contracting signals that work in InnerSource is managed professionally and inspires trust. +- A formal contracting increases transparency and provides a better overview about the associate's available capacity for his business unit and InnerSource projects, thus reducing the risk of "over-booked/planned capacity". A formal contracting is also beneficial for contributors and communities: -- With a stable group of contributors, it is more likely that some of them will - eventually achieve [Trusted Committer](./trusted-committer.md) status. -- A formal contracting provides a basis for resolving conflict related to - participation in InnerSource activities. Note that mediation will likely be - successful only for a few companies with a culture condusive to that. +- With a stable group of contributors, it is more likely that some of them will eventually achieve [Trusted Committer](./trusted-committer.md) status. +- A formal contracting provides a basis for resolving conflict related to participation in InnerSource activities. Note that mediation will likely be successful only for a few companies with a culture conducive to that. ## Known Instances -- _BIOS at Robert Bosch GmbH_. +- BIOS at Robert Bosch GmbH ## Status * Structured -* Old status: Proven ## Author @@ -148,3 +111,4 @@ A formal contracting is also beneficial for contributors and communities: - **2016-10-25** - first review - **2017-05-09** - rework - **2017-09-08** - second review, final rework and merged +- **2021-02-27** - fixing issues with display of the pattern in the book diff --git a/patterns/2-structured/core-team.md b/patterns/2-structured/core-team.md new file mode 100644 index 000000000..16c3133c6 --- /dev/null +++ b/patterns/2-structured/core-team.md @@ -0,0 +1,106 @@ +## Title + +Core Team + +## Patlet + +Even when an InnerSource project is widely needed, contributions and usage may be hindered because the project is difficult to work with. +Establish a core team that is dedicated to take care of the project's fundamental items. +Their work enables contributors to add and use the features that provide value to their scenarios. + +## Problem + +* It is difficult to contribute to the project. +This could be due to things like: + * Can't run the project locally. + * Poor documentation. + * Convoluted code. + * Inadequate testing. +* It is difficult to use the project. +Some possible causes: + * Poor documentation (again). + * Frequent bugs. + * Unintuitive setup. + +## Story + +There's a central project that everyone depends on. +What a great candidate for InnerSource! +Unfortunately, the project has grown organically, with various contributions and additions slapped on haphazardly. +Now it's an icky, thick morass of code that no one understands and everyone is afraid to touch. +It's clearly due for an overhaul (e.g. refactoring, testing, documentation, etc.), but even though everyone needs and wants that work to happen, no one takes the time to do it. + +## Context + +* Many teams need the project. +* The project has significant tech debt. +* Slow adoption and iteration on the project. +* There is not a owner or maintainer who takes reponsibility for the project and contribution ecosystem as a whole. + +## Forces + +* Every contributing team is busy, and therefore prioritizes work that results in an immediate payoff for themselves. +* As the project grows the natural trend is for it to become more difficult to use and to modify. + +## Solution + +Form a core team whose job it is to maintain this project in a state so that others can easily onboard and contribute to it. +This core team does the work that is necessary for a healthy usage and contribution ecosystem. +This critical work tends to not be prioritized as a contribution. +Categories of this type of work include communication, local environment, and DevOps infrastructure. + +Here are some specific examples: + +* Production bugs +* Documentation +* Onboarding tutorials and examples +* Automated testing +* CI/CD +* Local environment +* Modularization +* Versioning +* Monitoring +* Trailblazing new classes/categories of features + +Each of these items is very important to a healthy product ecosystem, yet is unlikely to be prioritized as a contribution. + +The core team may be composed of a small number of people on a full-time or a part-time basis. +The choice depends on the amount of work needed, the availability of resources, and the culture of the organization. +The most important consideration is to form the team in a way that allows the organization to empower and hold them accountable in the same way as any other team. + +Due to their central role, core team members should nearly always fill the role of [Trusted Committers][tc] as well. +While the [Trusted Committer][tc] role focuses mostly on facilitating others' contribution and use of the project, a core team member regularly contributes to the project as well. +The core team doesn't have its own business agenda that determines its contributions. +They decide what to work on based on what will help others most to use and contribute to the project. + +A good way to continually remind the core team of this goal is to have them report regularly on: + +* number of active teams using the project +* number of off-team contributions to the project. + +Continual focus on these metrics will naturally drive the core team to prioritize generally the right work to create a thriving InnerSource ecosystem around the project. + +## Resulting Context + +* It is easy to use and contribute to the project. +* Many teams use and contribute to the project. +* Core team has their success defined in terms of others' interaction with and response to their project. + +## Rationale + +Separating out a core team and tasking them in this way helps to fill the gaps that a successful project needs yet are left behind by contributors that are pursuing their own agenda only. +The core team fills those gaps and greases the wheels so that the contribution ecosystem remains healthy. + +## Known Instances + +Nike implemented this pattern to manage the InnerSource effort around its reusable CI/CD pipelines. + +## Status + +Structured + +## Author + +[Russell R. Rutledge](https://github.com/rrrutledge) + +[tc]: https://innersourcecommons.org/learn/learning-path/trusted-committer/ diff --git a/patterns/2-structured/crossteam-project-valuation.md b/patterns/2-structured/crossteam-project-valuation.md index 95320fc1f..bc0cbe12f 100644 --- a/patterns/2-structured/crossteam-project-valuation.md +++ b/patterns/2-structured/crossteam-project-valuation.md @@ -4,7 +4,7 @@ Cross-Team Project Valuation ## Patlet -It's hard to sell the value of cross-team, inner sourced projects that don't provide a direct impact on company revenue. +It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it. ## Context @@ -31,27 +31,27 @@ Such models give us the tool that we need to focus and amplify high-value collab The core of all cross-team project value is the idea that we can get more done together than apart. Ascribing value to a cross-team effort is an exercise in quantifying _how much more_ is getting done together. The exact delta in productivity will vary by domain and project. -There is a common process, though, by which you can create a model to calculate it. +There is a common process, by which you can create a model to calculate it. -## Explanation +### Explanation Assemble a small team of subject matter experts in your domain. Using that team of experts, estimate 4 things about each consumer of your project output: - * How long does it take them to consume your project output? - * How long would it otherwise take them to home-roll the value of your project output for themselves? - * What percentage of your project output is actually useful for them? - * How much time on an ongoing basis (ideally per-use) would they otherwise spend maintaining their home-rolled solution? +* How long does it take them to consume your project output? +* How long would it otherwise take them to home-roll the value of your project output for themselves? +* What percentage of your project output is actually useful for them? +* How much time on an ongoing basis (ideally per-use) would they otherwise spend maintaining their home-rolled solution? When making these estimations, it's impossible to know with high accuracy _exactly_ how long any activities take. That's not your goal. Rather than exactness, you should strive to _**set a worst-case bound**_ on these estimates. The idea is for the group of experts to be able to say to each other, "We don't know exactly how long it would take, but we can all agree it's _at least_ this much." Specifically, you should estimate a *maximum* reasonable time to consume your project output and *minimum* reasonable times for consumers to otherwise home-roll, use and maintain their own solutions. -> One note about cost-to home-roll. The cost to home-roll a solution is NOT necessarily (very unlikely, in fact) the same as the cost of making a shared solution. -Oftentimes for the same functionality the modularity and quality involved in buliding a cross-team, shared solution makes it a noticeably higher investment than a quick, hardcoded implementation used just once. +One note about cost of "rolling your own solution" (home-roll). The cost to home-roll a solution is NOT necessarily (very unlikely, in fact) the same as the cost of making a shared solution. +Oftentimes for the same functionality the modularity and quality involved in building a cross-team, shared solution makes it a noticeably higher investment than a quick, hardcoded implementation used just once. -## Formula +### Formula Once you have your worst-case bounds you can value your cross-team project output during a given time frame via the simple formula: @@ -63,21 +63,22 @@ Once you have your worst-case bounds you can value your cross-team project outpu [Count of New Onboardings] * ([Cost to Home-Roll] * [Percent Useful Functionality] - [Cost to Onboard]) + [Count of Usages] * [Maintenance Cost Per Use] ``` -## Commentary +### Commentary Despite the trappings of rigor, this process does not yield an exact way to measure cross-team project output. -In-practice, though, it does give a framework by which you can make a sound decision at how to fund this work. +In-practice, however, it does give a framework by which you can make a sound decision at how to fund this work. After having good, reasonable data according to the above explanation, you should fund dedicated development hours toward running the project up to _**at least**_ of the lesser of the following three levels: -1. The raw hours saved by the formula above. Since we're all sure that the formula will produce a number that is below the true number of hours saved, you can have confidence that funding the project up to that point is a sure win for you. -1. The amount of time that it takes to support inner sourced contributions to cross-team projects. Since the contributor would likely have done the work anyway in a one-off fashion, it is worth it to fund the time it takes to faciliate their work going into a shared location. -1. Whatever feels good to you. One intentional side-effect of having a valuation formula is that it naturally forces measurement of the key points of usage that provide value to consumers. +1. The raw hours saved by the formula above. Since we're all sure that the formula will produce a number that is below the true number of hours saved, you can have confidence that funding the project up to that point is a sure win for you. +1. The amount of time that it takes to support inner sourced contributions to cross-team projects. Since the contributor would likely have done the work anyway in a one-off fashion, it is worth it to fund the time it takes to facilitate their work going into a shared location. +1. Whatever feels good to you. One intentional side effect of having a valuation formula is that it naturally forces measurement of the key points of usage that provide value to consumers. + Those measurements can be understood and consumed in their raw form to provide you with a gut-feel idea of how valuable is the project. Some may be concerned about the lack of accuracy in this valuation approach. It's okay for this process to not give an exact measurement. It just needs to be accurate enough to accomplish 2 purposes: -1. Give a means to represent the value of what is happening to those that are organizing and funding cross-team efforts. -1. Help those involved to know what areas of cross-team effort are higher priority to pursue based on their value. +1. Give a means to represent the value of what is happening to those that are organizing and funding cross-team efforts. +1. Help those involved to know what areas of cross-team effort are higher priority to pursue based on their value. In-practice, as long as these valuations are within an order-of-magnitude of reality and one-another, they are sufficiently accurate to fill these purposes. They will provide a head-and-shoulders improvement in on-the-ground results over the ad-hoc valuations (and resultant effects) described in the **Problem** section at the beginning of this document. @@ -93,6 +94,11 @@ They will provide a head-and-shoulders improvement in on-the-ground results over * Nike +## Status + +* Structured +* Proven in multiple domains. + ## Authors * Russ Rutledge @@ -100,8 +106,3 @@ They will provide a head-and-shoulders improvement in on-the-ground results over ## Acknowledgement * Jeremiah Wright for teaching me to think about cross-team projects as an internal business dealing in the currency of developer time. - -## Status - -* Structured -* Old status: Proven in multiple domains. diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md index 7611723f6..ee8ae549f 100644 --- a/patterns/2-structured/dedicated-community-leader.md +++ b/patterns/2-structured/dedicated-community-leader.md @@ -1,6 +1,6 @@ ## Title -Dedicated Community Manager +Dedicated Community Leader ## Patlet @@ -8,7 +8,7 @@ Select people with both communications and technical skills to lead the communit ## Problem -How do you ensure that a new InnerSource initiative has the right [community manager](http://www.artofcommunityonline.org/) to grow it's impact? +How do you ensure that a new InnerSource initiative has the right [community leader](http://www.artofcommunityonline.org/) to grow it's impact? Selecting the wrong persons and/or not providing enough capacity for them risks wasted effort and ultimately the failure of a new InnerSource initiative. @@ -26,11 +26,11 @@ Consider the following story. A company wants to start an InnerSource initiative ## Forces -If a company does not significantly invest in the initial InnerSource community in terms of budget and capacity for InnerSource, the credibility of its commitment to InnerSource might be perceived as questionable. A common impulse of a company with a traditional management culture to a project or initiative not performing as expected will be to replace its leader. Doing that without involving the community and following meritocratic principles will further undermine the companies commitment to InnerSource by highlighting the friction between the current company culture and the target culture - a community culture. +If a company does not significantly invest in the initial InnerSource community in terms of budget and capacity for InnerSource, the credibility of its commitment to InnerSource might be perceived as questionable. A common impulse of a company with a traditional management culture to a project or initiative not performing as expected will be to replace its leader. Doing that without involving the community and following meritocratic principles will further undermine the company's commitment to InnerSource by highlighting the friction between the current company culture and the target culture - a community culture. The value contribution of InnerSource projects will not be obvious for many managers which are steeped in traditional project management methods. Those managers are less likely to assign one of their top people, who are usually in high demand by non InnerSource-projects, to an InnerSource project for a significant percentage of their work time. -Communication takes up a significant percentage of a community managers daily work. At the same time, he or she will likely also have to spearhead the initial development, too. In the face of limited capacity, inexperienced leaders will tend to focus on development and neglect communication. The barrier for potential contributors to make their first contribution and to commit to the community will be much higher if the community leader is hard to reach or is slow to respond to feedback and questions for lack of time. Furthermore, technically inexperienced leaders will most likely have a harder time to attract and retain highly experienced contributors than a top performer with a high degree of visibility within a company would have. +Communication takes up a significant percentage of a community leader's daily work. At the same time, he or she will likely also have to spearhead the initial development, too. In the face of limited capacity, inexperienced leaders will tend to focus on development and neglect communication. The barrier for potential contributors to make their first contribution and to commit to the community will be much higher if the community leader is hard to reach or is slow to respond to feedback and questions for lack of time. Furthermore, technically inexperienced leaders will most likely have a harder time to attract and retain highly experienced contributors than a top performer with a high degree of visibility within a company would have. If a community can not grow fast enough and pick up enough speed, chances are they won't be able to convincingly demonstrate the potential of InnerSource. @@ -52,7 +52,7 @@ Empower the community leader to dedicate 100 % of his time to community work inc ## Resulting Context -A community leader with the properties described above will lend a face and embody the companies commitment to InnerSource. It will make it more likely that other associates in his network will follow his lead and contribute to InnerSource. Over time, he or she will be able to build up a stable core team of developers and hence increase the chances of success for the InnerSource project. By convincingly a large enough audience within his company of the potential of InnerSource, he or she will make an important contribution to changing the company culture towards a community culture. +A community leader with the properties described above will lend a face and embody the company's commitment to InnerSource. It will make it more likely that other associates in his network will follow his lead and contribute to InnerSource. Over time, he or she will be able to build up a stable core team of developers and hence increase the chances of success for the InnerSource project. By convincing a large enough audience within his company of the potential of InnerSource, he or she will make an important contribution to changing the company culture towards a community culture. Having excellent and dedicated community leaders is a precondition for the success of InnerSource. It is, however, not a silver bullet. There are many challenges of InnerSource which are above and beyond what a community leader can tackle, such as budgetary, legal, fiscal or other organizational challenges. @@ -62,12 +62,11 @@ _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majorit ## Alias -Dedicated Community Leader +Dedicated Community Manager ## Status * Structured -* Old status: Proven ## Authors diff --git a/patterns/2-structured/gig-marketplace.md b/patterns/2-structured/gig-marketplace.md index 4b052a2a1..7e2ae3779 100644 --- a/patterns/2-structured/gig-marketplace.md +++ b/patterns/2-structured/gig-marketplace.md @@ -61,12 +61,11 @@ When used in combination with the InnerSource Portal pattern, the Gig Marketplac * A large financial services organization has used the creation of an InnerSource Gig Marketplace website to foster their InnerSource program. * SAP implemented the Gig Marketplace pattern - a new InnerSource program was added to the internal job platform where positions and similar offerings can be posted. -* The Gig Marketplace pattern has been proven to work extremely well with the associated InnerSource Portal pattern in this context. The InnerSource Portal increases awareness of specific projects currently underway while the Gig Marketplace advertises tasks of a certain type available to be worked on within those projects. +* The Gig Marketplace pattern has been proven to work extremely well with the associated [InnerSource Portal](./innersource-portal.md) pattern in this context. The InnerSource Portal increases awareness of specific projects currently underway while the Gig Marketplace advertises tasks of a certain type available to be worked on within those projects. ## Status * Structured -* Old status: Proven ## Author(s) diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md index f8ad3410f..37e199bdf 100644 --- a/patterns/2-structured/innersource-license.md +++ b/patterns/2-structured/innersource-license.md @@ -51,7 +51,7 @@ The license simplifies the conversations within our organization about sharing s ## Known Instances -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. +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. @@ -69,7 +69,6 @@ It is worth mentioning that so far the software shared under this InnerSource li ## Status * Structured -* Old status: Proven * The experiment listed under **Known Instances** is running since 02/2020. The initial experience shows first positive effects but more experience is needed to fully evaluate the pattern. ## Author(s) diff --git a/patterns/2-structured/innersource-portal.md b/patterns/2-structured/innersource-portal.md index f0d47c0d1..cc37c35ed 100644 --- a/patterns/2-structured/innersource-portal.md +++ b/patterns/2-structured/innersource-portal.md @@ -42,7 +42,7 @@ Visitors to the InnerSource portal should be able to see all available projects A communications campaign promoting the addition of InnerSource data files or meta-data to code repositories should also be considered in order to bolster the number of projects displayed within the portal. -![Example of an InnerSource Portal](https://github.com/SAP/project-portal-for-innersource/blob/main/overview.png?raw=true "Example of an InnerSource Portal") +![Example of an InnerSource Portal](https://raw.githubusercontent.com/SAP/project-portal-for-innersource/main/docs/overview.png "Example of an InnerSource Portal") ## Resulting Context @@ -65,7 +65,6 @@ The InnerSource Portal has enabled InnerSource project owners to advertise their ## Status * Structured -* Old status: Proven ## Author(s) diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md index ef46e6969..d4012eabc 100644 --- a/patterns/2-structured/maturity-model.md +++ b/patterns/2-structured/maturity-model.md @@ -5,15 +5,15 @@ Maturity Model ## Patlet Teams have started adopting InnerSource. The practice is spreading to multiple -departments. Understanding of what constitutes an InnerSource project are wide -spread though. The solution is to provide a maturity model to allow for teams to -go through a self check and discover patterns and practices that they are not +departments. However, the understanding of what constitutes an InnerSource +project varies. The solution is to provide a maturity model to allow for teams +to go through a self check and discover patterns and practices that they are not yet aware of. ## Problem When InnerSource adoption in an enterprise starts to increase, individual -mentoring of each project through one evangelist becomes unfeasible. Also more +mentoring of each project through one evangelist becomes unfeasible. Also, more and more people are gaining at least a basic understanding of what it means to work in an InnerSource project. Looking at all InnerSource projects though the depth of understanding for the concept will diverge. Teams may not be aware of @@ -34,7 +34,7 @@ Teams sharing InnerSource learnings run into misunderstandings as they are not aware of their respective level of InnerSource adoption. Teams believe that "it's all about migrating to a shared software development -forge". +[forge](https://en.wikipedia.org/wiki/Forge_%28software%29)" (GitLab, GitHub, or Bitbucket being well known examples of such forges). Teams are not aware of best practices that would help them solve issues that they run into in their daily doing. @@ -51,7 +51,7 @@ InnerSource project benefit from planning being transparent across the organizat * PP-0: Individuals and teams do not regularly disclose their plans or products to multiple stakeholders. No formal actions exists at the organization. * PP-1: Individuals and teams give visibility to their plans or products to multiple stakeholders, before they are started. Shared roadmap. -* PP-2: There are already shared roadmaps with clear guidelines and contribution rules where stakeholders can provide feedback. However this is not standardized across the organization and not all of the projects provide this info. +* PP-2: There are already shared roadmaps with clear guidelines and contribution rules where stakeholders can provide feedback. However, this is not standardized across the organization and not all of the projects provide this info. * PP-3: Roadmaps are shared by default and there is a standard process and homogeneous way to do this across the organization at the level of each InnerSource project. This contains clear rules to contribute and influence in the roadmap. **Development Process & Tools** @@ -60,16 +60,16 @@ InnerSource projects thrive when contributors become active and participate. As * DP-0: Each team follows its own development process and tools. They are not defined to share knowledge and artifacts outside development team. Siloed development teams. * DP-1: Development teams use shared code repositories, internally. Some teams develop their own CI process, using non corporate or standard CI tools. There is no code review process defined, although some projects teams do it internally. -* DP-2: The organization sponsors and promotes a shared repository for collective knowledge. Some teams develop their own CI process, using corporate CI tools. There are CI environments. Code review process defined, and used by some projects. Code review is sometimes done by external team members. +* DP-2: The organization sponsors and promotes a shared repository for collective knowledge. Some teams develop their own CI process, using corporate CI tools. There are CI environments. Code review process defined, and used by some projects. Sometimes code review is done by outside team members. * DP-3: Most teams develop their own CI process, using corporate CI tools. There are CI environments. Code review process defined, and used. Code review is done by both, internal and external team members. **Decisions** -In order to motivate colleagues to contribute work outside of their core team they need visibility into the decision making process of the host project - but also feel that their voices are being heard and valued. +In order to motivate colleagues to contribute work outside of their core team they need visibility into the decision-making process of the host project - but also feel that their voices are being heard and valued. * DC-0: Decision-makers often intentionally or accidentally withhold data and resources related to project decisions. * DC-1: Materials that are part of decision-making practices become available for review after decisions are finalized. -* DC-2: People feel like they know about—and are helping to shape—most (but not all) important decisions as those decisions are unfolding. Materials that are part of decision-making practices are available at defined project milestones +* DC-2: People feel like they know about—and are helping to shape—most (but not all) important decisions as those decisions are unfolding. Materials that are part of decision-making practices are available at defined project milestones. * DC-3: People feel like they are a part of a shared, standard process for collective decision-making that the organization endorses. Materials that are part of decision-making practices are continuously accessible during work processes. **Helpful Resources** @@ -85,7 +85,7 @@ In order to attract contributors helpful supporting material needs to be easily When working in host teams mistakes will automatically be widely visible. In order keep contribution levels up, corporate culture needs to celebrate failure as an opportunity for growth and learning. -* ST-0: Individuals and teams don't share neither successes nor failures for others to learn from. +* ST-0: Individuals and teams do not share successes or failures for others to learn. * ST-1: Individuals and teams are comfortable sharing stories about successes, but not about failures. * ST-2: Individuals and teams are comfortable sharing stories of successes and failures during retrospectives and reviews. * ST-3: Individuals and teams are comfortable sharing stories of successes and failures, and learn from failures according to formal protocols. @@ -168,7 +168,7 @@ InnerSource projects need a means for self assessment. Metrics can be one aspect * MP-0: No existing monitoring policies at any level in the organization. * MP-1: Metrics are important for certain teams, and they start using them in an isolated way. -* MP-2: There is a strategy at the organizational level with respect to metrics that help to validate specific policies across the organization. This monitoring policy exists at the level of some of the InnerSource projects. +* MP-2: There is a strategy at the organizational level with respect to metrics that help to validate specific policies across the organization. This monitoring policy exists at the level of some InnerSource projects. * MP-3: There are clear guidelines, recommendations, and trainings about the use of metrics with certain infrastructure provided by the organization. This works at both levels: InnerSource program to understand the general InnerSource adoption within the organization, and at the level of InnerSource projects. **Support and Maintenance** @@ -177,7 +177,7 @@ Not only should feature development be owned by InnerSource teams - support and * SP-0: Support given by the core dev or support team. A business contract guaranties the support. There is no knowledge about the product outside the team. * SP-1: There are rules and regulations to formalize the support on the product, given by a dedicated supporting team. -* SP-2: Support for InnerSource contributions is formalized through InnerSource patterns like [30 day warranty](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/30-day-warranty.md) or [service vs. library](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/master/patterns/2-structured/service-vs-library.md). +* SP-2: Support for InnerSource contributions is formalized through InnerSource patterns like [30 Day Warranty](./30-day-warranty.md) or [Service vs. Library](./service-vs-library.md). * SP-3: There are rules and regulations to formalize the support on the product, given by a mature community. **Culture** @@ -195,7 +195,7 @@ InnerSource comes with explicit roles. While in early stages some patterns may b * RO-0: There are no specific roles helping InnerSource adoption. Only common development roles are present: developer, analyst, tester, etc. * RO-1: Occasionally some individuals and teams contribute to other projects. These are technical contributions, where the user/contributor role is seen. For some teams, it can be identified at least one member being a technical reference, who explains the development process to other development team members. He/she could be a candidate for covering the trusted committer role. -* RO-2: An InnerSource Officer role is in charge for governance and support, including processes, etc. Identifies the education needs and ensures it is provided to the organization. Leads and mentors the organization in the engagement in IS projects. Is the first formal step in the way, defining the IS vision and roadmap. The organization has defined a trusted committer role, being a point of contact/reference not only for dev team members but also for external contributors. There is a standard process describing how to contribute to the community, contributor role is present. Data Scientist role is in charge of managing the traces of activity left by the InnerSource initiative, needed to measure the IS evolution. Trusted committer role will evolve to a more technical profile, and a community manager will be in charge of "energizing" the community, being his main responsibility to attract and retain new developers/users (contributors/community members). +* RO-2: An InnerSource Officer role is in charge of governance and support, including processes, etc. Identifies the education needs and ensures it is provided to the organization. Leads and mentors the organization in the engagement in IS projects. Is the first formal step in the way, defining the IS vision and roadmap. The organization has defined a trusted committer role, being a point of contact/reference not only for dev team members but also for external contributors. There is a standard process describing how to contribute to the community, contributor role is present. Data Scientist role is in charge of managing the traces of activity left by the InnerSource initiative, needed to measure the IS evolution. Trusted committer role will evolve to a more technical profile, and a community manager will be in charge of "energizing" the community, being his main responsibility to attract and retain new developers/users (contributors/community members). * RO-3: Evangelists are moving inside organization, to let others know about the current work, what InnerSource does and how to do it, and help others to understand and become part of the initiative. Non technical contributors appear. ## Resulting Context @@ -205,7 +205,7 @@ All teams are aware of available best practices. Teams understand their level of InnerSource adoption. Prior to adopting InnerSource as a working model, teams are aware of the -practices that are expected of them - both in the short term as well as in the +practices that are expected of them - both in the short term and in the long term. ## Known Instances @@ -223,6 +223,8 @@ long term. ## Acknowledgements +* Alexander Andrade (special thanks for the spelling fixes) + ## Alias Maturity model: Learn about InnerSource best practices diff --git a/patterns/2-structured/praise-participants.md b/patterns/2-structured/praise-participants.md index 0d03145ba..27dc7aecc 100644 --- a/patterns/2-structured/praise-participants.md +++ b/patterns/2-structured/praise-participants.md @@ -5,7 +5,7 @@ Praise Participants ## Patlet After an inner source contribution, it's important to thank the contributor for their time and effort. -This pattern gives guidance that not only effectively acknowledges the contribution but also endgenders further engagement from the contributor and others. +This pattern gives guidance that not only effectively acknowledges the contribution but also engenders further engagement from the contributor and others. ## Problem @@ -21,7 +21,7 @@ A pattern in this area makes it easy to do and ensures that the message comes ac ## Forces -* You are busy, which makes it easy to forget some of the soft touches like praise and thanks. +* You are busy, which makes it easy to forget some soft touches like praise and thanks. * You may not be someone that is comfortable in social situations or good with words. * Peer recognition is very important to job satisfaction and career development. @@ -31,15 +31,19 @@ It feels good to anyone to be recognized by others. In a professional setting, increased recognition is also an avenue to increased influence and growth. Any time someone gives to your inner source project, recognize them with a sincere and qualified "thank you". -For non-trivial contributions (all code contributions and also significant time contributions), say thank you via the following mechanisms: +For non-trivial contributions (all code contributions and significant time contributions), say thank you via the following mechanisms: -1. Call out the person by name in any chat location (e.g. _Slack_) where you organize your project activity. Let everyone know what they did and thank them publicly. Example: +(1) Call out the person by name in any chat location (e.g. _Slack_) where you organize your project activity. Let everyone know what they did and thank them publicly. + +Example: > Everyone @here give a high-five to @andrew.clegg for updating the _rcs-viewer_ to the latest version of the _hebo-client_ (https://github.com/rcs/rcs-viewer/pull/81). Thanks for helping keep this library up-to-date, Andy! -2. Send an email to them and their manager (cc'd) privately thanking them for the contribution. -For code contributions often-times you can just forward the merge notification mail. Example: +(2) Email them and their manager (cc'd) privately thanking them for the contribution. +For code contributions often-times you can just forward the merge notification mail. + +Example: > Hi, Andy, I want to thank you again for making this update. It may have been a small amount of time, but it's attention like this from each person that make the RCS project work for all of us. @@ -68,7 +72,6 @@ Overdoing it may feel insincere and mechanical and defeat your purpose in reachi ## Status * Structured -* Old status: Proven ## Author(s) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index c3ba2d426..d278ff35e 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -105,7 +105,7 @@ started right away: [README-template.md](templates/README-template.md) and ## Known Instances -* Europace AG +* Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) * Paypal Inc. ## Authors diff --git a/patterns/2-structured/project-setup/communication-tooling.md b/patterns/2-structured/project-setup/communication-tooling.md index 3c35043ef..e7fe502c1 100644 --- a/patterns/2-structured/project-setup/communication-tooling.md +++ b/patterns/2-structured/project-setup/communication-tooling.md @@ -6,7 +6,7 @@ Communication Tooling An InnerSource project is being used outside the original development team but users are having trouble getting help and getting in touch with the project -team. The idea is to setup and document standard communication tooling that +team. The idea is to set up and document standard communication tooling that allows for discussions to become visible, archived and searchable. ## Context @@ -39,9 +39,9 @@ The goal when streamlining communication channels for InnerSource projects should be to align communication around topics, not around certain sets of people: -- The project should have it's own 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. -- The project should have one or more discussion channels that come with less rigid a structure. Typically this will be mailing lists, online forums or even archived chat channels. Usually it is enough to start with just one channel for the project, if traffic increases too much it's helpful to split discussions around project usage from discussions around project development. -- In addition the project should have one private channel where sensitive communication 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. +- The project should have its own 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. +- The project should have one or more discussion channels that come with less rigid a structure. Typically, this will be mailing lists, online forums or even archived chat channels. Usually it is enough to start with just one channel for the project, if traffic increases too much it's helpful to split discussions about project usage from discussions about project development. +- In addition, the project should have one private channel where sensitive communication 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 written channels, as much information as possible should be brought back to the asynchronous channels. @@ -71,7 +71,7 @@ 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 on find) the previous answer leading +users with the same question see (or later find) the previous answer leading to a lower need to repeat explanations. ## Known Instances diff --git a/patterns/2-structured/project-setup/issue-tracker.md b/patterns/2-structured/project-setup/issue-tracker.md index 8ddd58eb8..ffbda0591 100644 --- a/patterns/2-structured/project-setup/issue-tracker.md +++ b/patterns/2-structured/project-setup/issue-tracker.md @@ -10,13 +10,13 @@ The InnerSource host team fails to make not only plans and progress but also con 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 +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 +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. @@ -25,7 +25,7 @@ communication easier. - 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 of the easier issues that are open already. As a result a lot of work remains in the hands of the host team. +- 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 @@ -36,20 +36,20 @@ 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 brain storming 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. +- 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 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 +* Europace AG - See blog post [Issue Use Cases](https://tech.europace.de/post/using-issues-for-asking-questions-and-tracking-work/) ## Authors diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md index d1d1afef0..559667d0e 100644 --- a/patterns/2-structured/repository-activity-score.md +++ b/patterns/2-structured/repository-activity-score.md @@ -4,7 +4,7 @@ Repository Activity Score ## Patlet -Potential contributors want to find active InnerSource projects in need of their help. By calculating a repository activity score for each project, a ranked list of projects can be created (e.g. on the [InnerSource portal](innersource-portal.md)), so that potential contributors can more easily determine which project they want to contribute to. +Potential contributors want to find active InnerSource projects in need of their help. By calculating a repository activity score for each project, a ranked list of projects can be created (e.g. on the [InnerSource Portal](innersource-portal.md)), so that potential contributors can more easily determine which project they want to contribute to. ## Problem @@ -112,7 +112,6 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Status * Structured -* Old status: Proven ## Author(s) diff --git a/patterns/2-structured/review-committee.md b/patterns/2-structured/review-committee.md index 7a65658b4..422b50a62 100644 --- a/patterns/2-structured/review-committee.md +++ b/patterns/2-structured/review-committee.md @@ -40,19 +40,18 @@ Company A wants to introduce its first InnerSource initiative. Most managers in ## Known Instances -BIOS at Robert Bosch GmbH - -## Alias - -Cheese Interface +* BIOS at Robert Bosch GmbH ## Status -Proven - -_Finalized and Reviewed_ as of 8/31/17. +* Structured +* _Finalized and Reviewed_ as of 8/31/17. ## Authors - Georg Grütter, Robert Bosch GmbH - Diogo Fregonese, Robert Bosch GmbH + +## Alias + +Cheese Interface diff --git a/patterns/2-structured/service-vs-library.md b/patterns/2-structured/service-vs-library.md index 759f6a014..8d046208b 100644 --- a/patterns/2-structured/service-vs-library.md +++ b/patterns/2-structured/service-vs-library.md @@ -73,7 +73,7 @@ the implementation. ## See also -Related to this pattern is the [Thirty day warranty](30-day-warranty.md) pattern that takes a different approach to solving the forces described above. +Related to this pattern is the [30 Day Warranty](30-day-warranty.md) pattern that takes a different approach to solving the forces described above. ## Known Instances @@ -82,7 +82,6 @@ Europace AG ## Status * Structured -* Old status: Proven ## Author(s) diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md index 426b772e9..12844e465 100644 --- a/patterns/2-structured/start-as-experiment.md +++ b/patterns/2-structured/start-as-experiment.md @@ -4,94 +4,52 @@ Start as an Experiment ## Patlet -Start your InnerSource initiative as a time limited experiment to make it -easier for managers unfamiliar with InnerSource to endorse and support the -initiative. +Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative. ## Problem -An InnerSource initiative is considered but not started because management is -unsure about its outcome and, as a result, is not willing to commit to an -investment. +An InnerSource initiative is considered but not started because management is unsure about its outcome and, as a result, is not willing to commit to an investment. ## Context -The company is considering InnerSource to increase the efficiency -of collaboration on software projects. However, most managers are not familiar -with the Open Source working model and are instead accustomed to hierarchical, -top-down control style management. The idea of InnerSource is very popular with -software developers in the company, not the least because many developers use -or are actively developing Open Source software. +The company is considering InnerSource to increase the efficiency of collaboration on software projects. However, most managers are not familiar with the Open Source working model and are instead accustomed to hierarchical, top-down control style management. The idea of InnerSource is very popular with software developers in the company, not the least because many developers use or are actively developing Open Source software. ## Forces -- Managers will want to validate the claims of improved collaboration through - InnerSource before making a long term investment. This usually involves - measuring the improvements. -- If the InnerSource initiative will likely have a huge uptake among developers - and if many projects are likely to rely on it, a decision to shut it down - will be very unpopular and therefore hard to make. The perceived resulting - loss of control might deter some managers to even start with InnerSource. -- Implementing InnerSource style working models are often a radical departure - from previously practiced working models. It is therefore likely, that - existing, mandatory processes are no longer applicable and that appropriate - governing processes are missing. The result might be that one has to operate - in a regulatory, sometimes legal no-mans land. Examples are tax and export - control related regulations in large corporations with multiple legal - entities in multiple countries. +- Managers will want to validate the claims of improved collaboration through InnerSource before making a long term investment. This usually involves measuring the improvements. +- If the InnerSource initiative will likely have a huge uptake among developers and if many projects are likely to rely on it, a decision to shut it down will be very unpopular and therefore hard to make. The perceived resulting loss of control might deter some managers to even start with InnerSource. +- Implementing InnerSource style working models are often a radical departure from previously practiced working models. It is therefore likely, that existing, mandatory processes are no longer applicable and that appropriate governing processes are missing. The result might be that one has to operate in a regulatory, sometimes legal no-mans land. Examples are tax and export control related regulations in large corporations with multiple legal entities in multiple countries. ## Solution -Declare the InnerSource initiative as a time limited experiment. Define and -communicate the criteria for projects to join the InnerSource experiment. Choose -criteria that will maximize the chances of building a healthy A set of criteria is -a good one if the insights generated from it within the context of the experiment -can intuitively be applied to contexts involving other potential InnerSource projects. +Declare the InnerSource initiative as a time limited experiment. Define and communicate the criteria for projects to join the InnerSource experiment. Choose criteria that will maximize the chances of building a healthy community. A set of criteria is a good one if the insights generated from it within the context of the experiment can intuitively be applied to contexts involving other potential InnerSource projects. + Examples for such criteria are: - Sufficient geographical distribution of developers -- Sufficient departmental mix of developers, -- Openness of communication within community, -- Career path based on merit within community, -- Democratic decision making within community. - -Consider designating the end of the experiment a _pivot_, _change_ or _pause_ -point to re-evaluate. Also consider establishing a [Review -Committee](review-committee.md) to increase the chances of management buy-in -through participation. Depending on company culture, it might be helpful to -accompany the experiment with appropriate metrics [First Steps With -Metrics](../1-initial/introducing-metrics-in-innersource.md). If the projects in the -experiment don't provide a direct impact on the companies revenue, consider -introducing [Cross Team Valuation](crossteam-project-valuation.md) to highlight -their value contributions. +- Sufficient departmental mix of developers +- Openness of communication within community +- Career path based on merit within community +- Democratic decision making within community + +Consider designating the end of the experiment a _pivot_, _change_ or _pause_ point to re-evaluate. Also consider establishing a [Review Committee](review-committee.md) to increase the chances of management buy-in through participation. Depending on company culture, it might be helpful to accompany the experiment with appropriate metrics [First Steps With Metrics](../1-initial/introducing-metrics-in-innersource.md). If the projects in the experiment don't provide a direct impact on the companies revenue, consider introducing [Cross-Team Project Valuation](crossteam-project-valuation.md) to highlight their value contributions. ## Resulting Context Managers are able to kick start InnerSource for the following reasons: -- The experimental setup eases the need for managers to scrutinize the - InnerSource program numbers in the same way that they would for typical - projects. -- The possibility of failure of the experiment is understood and accepted. The - personal risk for the supporting managers is minimized. -- Even in case of a failure, the setup ensures that the company will learn from - the experiment. -- In case of success, the data gathered during the experiment will allow - managers to make a longer lasting commitment to InnerSource. - -Participants in the InnerSource experiment are now conscious that they have to -prove to management that InnerSource yields the promised benefits. -It will therefore help to focus work on those activities which provide the most -demonstrable value thus increasing the chances of success. - -Finally, starting as an experiment makes it much easier to sidestep regulations -and forces such as tool and process policies which could decrease the chances -of success. +- The experimental setup eases the need for managers to scrutinize the InnerSource program numbers in the same way that they would for typical projects. +- The possibility of failure of the experiment is understood and accepted. The personal risk for the supporting managers is minimized. +- Even in case of a failure, the setup ensures that the company will learn from the experiment. +- In case of success, the data gathered during the experiment will allow managers to make a longer lasting commitment to InnerSource. + +Participants in the InnerSource experiment are now conscious that they have to prove to management that InnerSource yields the promised benefits. It will therefore help to focus work on those activities which provide the most demonstrable value thus increasing the chances of success. + +Finally, starting as an experiment makes it much easier to sidestep regulations and forces such as tool and process policies which could decrease the chances of success. ## Related Patterns -- _Trial Run_ (from the book [_Fearless - Change_](https://fearlesschangepatterns.com/)) +- _Trial Run_ (from the book [Fearless Change](https://fearlesschangepatterns.com/)) ## Known Instances @@ -100,7 +58,6 @@ of success. ## Status * Structured -* Old status: Proven ## Author diff --git a/patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md b/patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md index ced2f2560..54baaf08b 100644 --- a/patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md +++ b/patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md @@ -57,7 +57,7 @@ Important elements of the solution are: - appropriate tooling chosen (e.g. non-engineers may not have access to source control tools) - a commitment to iterate on the RFC template and process -### Examples/templates +### Examples/Templates - [Rust][rust] is a good Open Source example of RFC template and process, and has been the basis for many other RFC processes. - [Genericised BBC iPlayer & Sounds RFC template](templates/rfc.md), originally based on the [Rust][rust] template @@ -100,7 +100,7 @@ Also for decision making outside of pure software design decisions, transparent ## Status -**Structured** +Structured ## Author(s) diff --git a/patterns/2-structured/trusted-committer.md b/patterns/2-structured/trusted-committer.md index bc206d9fe..382f99f79 100644 --- a/patterns/2-structured/trusted-committer.md +++ b/patterns/2-structured/trusted-committer.md @@ -4,67 +4,51 @@ Trusted Committer ## Patlet -Many inner-source projects will find themselves in a situation where +Many InnerSource projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. -In these situations project maintainers seek ways to recognize and reward the +In these situations, project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions. ## Problem - - Project maintainers want to find ways to scale their ability to support a - project - - Project maintainers want to find ways to lengthen the value delivered by a - project - - Project maintainers want to visibly reward frequent contributors and - empower them to amplify their value contribution. - - Lack of language for recognizing contributions across teams within an - organization +- Project maintainers want to find ways to scale their ability to support a project +- Project maintainers want to find ways to lengthen the value delivered by a project +- Project maintainers want to visibly reward frequent contributors and empower them to amplify their value contribution. +- Lack of mechanism and language for recognizing contributions across teams within an organization ## Context - - You are the maintainer of a cross-team library, service, or shared resource - - You receive regular contributions - - There are motivated contributors looking to build expertise through - inner-sourced projects +- You are the maintainer of a cross-team library, service, or shared resource +- You receive regular contributions +- You receive regular feature requests +- You receive regular bug-fix requests +- There are motivated contributors looking to build expertise through InnerSource projects ## Forces - - Over the lifecycle of a project the focus of the maintainers may shift away - to accommodate changing business priorities - - Contributors seek visible artifacts of their contributions demonstrating - value - - Maintaining a project of reasonable complexity is taxing for a small team +- Over the lifecycle of a project, the focus of the maintainers may shift away to accommodate changing business priorities +- Contributors seek visible recognition of their contributions, demonstrating value +- Maintaining a project of reasonable complexity is taxing for a small team +- Developing project features at scale is taxing for a small team ## Solution ### Defining the Trusted Committer Role for a Project -What a Trusted Committer handles is up to each project and its maintainers. -Whatever shape your Trusted Committer role takes, make sure it's clearly -documented somewhere in your project. This sets expectations for new community -members and outlines the role for future candidates. +What a Trusted Committer handles is up to each project and its maintainers. Ensure you document within the project the scope of your Trusted Committer role. Clear documentation sets expectations for new community members and establishes the role for future candidates. -Below we've provided a few guidelines for what Trusted Committers can be -invited to do: +The following are a few guidelines for identifying a potential Trusted Committer: -* If a candidate participates often in community channels (e.g. Slack, JIRA -issue triaging, etc.) then becoming a Trusted Committer formalizes their role -in community support. - -* A good candidate for a Trusted Committer, is someone who frequently submits -code, documentation, or other repository changes. Start by including this -person on pull requests. If they are actively engaging in pull requests, -consider approaching them about opportunities for further collaboration on the -project. +* An active participant in community channels (Slack, JIRA issue triaging, etc.) becomes a Trusted Committer, thereby formalizing their role in community support. +* Someone who frequently submits code, documentation, or other repository changes. Start by including this person on pull requests. If they are actively engaging in pull requests, consider approaching them about opportunities for further collaboration on the project. ### Formalizing Trusted Committers The first step is to approach candidates about becoming a Trusted Committer. -Maintainers should make sure candidates understand the role. To be clear: -there is no expectation that candidates will accept the role. Each candidate -should figure out if they have the bandwidth to get involved. +Maintainers should educate candidates on the role of a Trusted Committer. There is no expectation that candidates will accept the role of Trusted Committer. Each candidate +should assess if they have the available bandwidth to take on the responsibilities. -When a candidate accepts the role it is up to the project maintainers to +When a candidate accepts the role, it is up to the project maintainers to publicly recognize the transition from user to Trusted Committer. It is also a good idea to add their name to a Trusted Committers section in your project's README. As an example: @@ -89,50 +73,49 @@ README. As an example: ### Maintaining Trusted Committer Relationships -When a new Trusted Committer is minted it’s a good idea to keep them in the -loop as you continue to iterate on your project. This can be as simple as -inviting them to your project channel or as involved as including them in your +Once you formalize a new Trusted Committer, it is a good idea to keep them in the +loop as you continue to iterate on your project. Keeping them in the loop can be as +simple as inviting them to your project channel or as involved as including them in your planning sessions. More opportunities for involvement gives Trusted Committers a path to Maintainer if they so desire. -Besides keeping Trusted Committers informed it’s a good idea to check in on a -regular basis. A good cadence is every week, but as the Trusted Committer -settles in this can drop to every few weeks or so. The purpose of these -check-ins is to make sure the Trusted Committer feels supported in their new -role, like a 1:1 with your manager. If things aren’t going well, listen and -try to understand what is preventing the Trusted Committer from being successful. -If things are going well, [thank the Trusted Committer for their continued -effort][praise] in making the project successful and set a new date to check-in. +Besides keeping Trusted Committers informed, it is good to check in on a +regular basis. A suggested cadence is to start with every week before gradually +progressing to every few weeks. The purpose of these check-ins is to make sure the +Trusted Committer feels supported in their new role. Analogous to a 1:1 with your +manager, if there are any issues, listen and empathize to try and understand +what is preventing the Trusted Committer from being successful. Always +[thank the Trusted Committer for their continued effort][praise] in making the project successful and set a new date to check-in. ### Sunsetting a Trusted Committer -There comes a time when removal of a Trusted Committer is necessary, for -example: +There are times which necessitate removing a Trusted Committer, such as if the Trusted +Committer is: * No longer willing to take part * No longer able to perform their duties * No longer employed by the company -In each of the above cases a plan for removing access to project resources -should be agreed upon by both parties. This includes transitioning their entry in -a project's **Trusted Committer** section to a list of past contributors. +A plan for removing access to project resources should be agreed upon by both parties, +including transitioning their entry in a project's **Trusted Committer** section to a +list of past contributors. -After access is removed it is courteous to [thank the Trusted Committer for -their participation in a public way][praise]. This ensures clear communication -and continuity within the community. +Upon removing access, [thank the Trusted Committer for +their participation publicly][praise]. Public acknowledgment ensures clear +communication of transition and continuity within the community. ## Resulting Context ### For Contributors -Achieving Trusted Committer status for a project is a sign that the contributor -has demonstrated an improvement to a community project. Recognition for these +Achieving Trusted Committer status for a project demonstrates initiative in +contributing to the community project. Recognition for these efforts can be used during annual reviews with managers. ### For Maintainers As a project matures, maintainers can become less familiar with key aspects -of a project. Trusted Committers fill in these gaps. This ensures that all +of a project. Trusted Committers fill in these gaps, ensuring that all aspects of the project are better served over time. A healthy set of Trusted Committers ensures that if project maintainers move on @@ -140,13 +123,15 @@ there is a plan for responsible stewardship. ## Known Instances -This has been tried and proven successful at Nike and PayPal. +This has been tried and proven successful at: -## Status +- Nike +- PayPal -Proven +## Status -Published internally at Nike; drafted via pull-request in June of 2018. +- Structured +- Published internally at Nike; drafted via pull-request in June of 2018. ## Authors @@ -158,9 +143,9 @@ Published internally at Nike; drafted via pull-request in June of 2018. - [Loren Sanz] - [Noah Cawley] - [Jeremy Hicks] +- [Doron Katz] -## Variants - +[Doron Katz]: https://github.com/doronkatz [Russell Rutledge]: https://github.com/rrrutledge [Loren Sanz]: https://github.com/mrsanz [Jeremy Hicks]: https://github.com/greatestusername