diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 31b823e78..64c007274 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,7 +1,7 @@ blank_issues_enabled: true contact_links: - name: Slack - url: https://innersourcecommons-inviter.herokuapp.com + url: https://innersourcecommons.org/slack about: Join our Community on Slack for help and a casual chat. - name: Patterns Book url: https://patterns.innersourcecommons.org diff --git a/.github/config.yml b/.github/config.yml new file mode 100644 index 000000000..bac200892 --- /dev/null +++ b/.github/config.yml @@ -0,0 +1,44 @@ +# Configuration for welcome - https://github.com/behaviorbot/welcome + +# Configuration for new-issue-welcome - https://github.com/behaviorbot/new-issue-welcome + +# Comment to be posted to on first time issues +newIssueWelcomeComment: > + [![Welcome Banner](https://zenodo.org/api/iiif/v2/0c0188d3-d03c-4830-a6e3-00405f5c22fa:8ff47a85-7250-4d86-8e48-2f346b48b2c1:BannerWelcome.jpg/full/750,/0/default.jpg)](https://zenodo.org/record/3695300) + + :tada: Welcome to _The InnerSource Commons_ community, and in particular to our patterns! :tada: + We're really excited to have your input into the project! :sparkling_heart: + +
If you haven't done so already, please check out our [Contributing Guidelines](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/CONTRIBUTING.md). + If you need to connect more synchronously with members of _The InnerSource Commons_ community, come chat with us in our [Slack workspace](https://innersourcecommons.org/slack). + +# Configuration for new-pr-welcome - https://github.com/behaviorbot/new-pr-welcome + +# Comment to be posted to on PRs from first time contributors in your repository +newPRWelcomeComment: > + [![Thank You Banner](https://zenodo.org/api/iiif/v2/0c0188d3-d03c-4830-a6e3-00405f5c22fa:7fbd97cf-283b-480c-b8e1-11866e26245c:BannerThanks.jpg/full/750,/0/default.jpg)](https://zenodo.org/record/3695300) + + :sparkling_heart: Thanks for opening this pull request! :sparkling_heart: + _The InnerSource Commons_ community really appreciates your time and effort to contribute to the project. + Please make sure you have read our [Contributing Guidelines](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/CONTRIBUTING.md). + + If you are submitting a new pattern, the following things will help get your pull request across the finish line! :checkered_flag: + + - Check you have used our [pattern template](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/pattern-template.md) and removed any placeholder text and sections that your pattern did not need. + + - We will run a number of automated checks on your PR. Please review the output of those checks on the PR itself, and see if any issues got flagged that you can fix yourself. + + - Make sure you have added your new pattern to the list of patterns in the main [README.md](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/README.md). If you are unsure where to add your pattern, no worries. Just let us know on the PR and we will help you. + +
This project has a small number of maintainers, volunteering their time to this project. So please be patient and we will get back to you as soon as we can. + If we don't acknowledge this pull request after 7 days, feel free to chat to us about it in our [Slack workspace](https://innersourcecommons.org/slack). + +# Configuration for first-pr-merge - https://github.com/behaviorbot/first-pr-merge + +# Comment to be posted to on pull requests merged by a first time user +firstPRMergeComment: > + [![Congratulations Banner](https://zenodo.org/api/iiif/v2/0c0188d3-d03c-4830-a6e3-00405f5c22fa:32fbdb89-ae1b-434e-830c-88ade86724cc:BannerCongratulations.jpg/full/750,/0/default.jpg)](https://zenodo.org/record/3695300) + + Congrats on merging your first pull request! :tada: + We here at _The InnerSource Commons_ are proud of you! :sparkling_heart: + Thank you so much for your contribution :gift: diff --git a/lint/pattern-template.js b/.github/lint-pattern-syntax/pattern-template.js similarity index 100% rename from lint/pattern-template.js rename to .github/lint-pattern-syntax/pattern-template.js diff --git a/lint/pattern-template.yml b/.github/lint-pattern-syntax/pattern-template.yml similarity index 100% rename from lint/pattern-template.yml rename to .github/lint-pattern-syntax/pattern-template.yml diff --git a/.github/vale/Vocab/Base/accept.txt b/.github/vale/Vocab/Base/accept.txt new file mode 100644 index 000000000..799a7d044 --- /dev/null +++ b/.github/vale/Vocab/Base/accept.txt @@ -0,0 +1,6 @@ +Manoj +Gawande +Dinesh +Ramadoss +Amit +Chauhan \ No newline at end of file diff --git a/.github/vale/Vocab/Base/reject.txt b/.github/vale/Vocab/Base/reject.txt new file mode 100644 index 000000000..e69de29bb diff --git a/.github/workflows/i18n-consistency-checker.yaml b/.github/workflows/i18n-consistency-checker.yaml new file mode 100644 index 000000000..2f173fada --- /dev/null +++ b/.github/workflows/i18n-consistency-checker.yaml @@ -0,0 +1,104 @@ +name: i18n check consistency and notify on GitHub Issues + +on: + pull_request: + branches: + - master + paths: + - .github/workflows/i18n-consistency-check.yml + schedule: + - cron: '0 0 1 * *' + workflow_dispatch: + +jobs: + consistency-check: + runs-on: ubuntu-latest + strategy: + matrix: + language: [ja, zh] + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: '0' + - name: Check consistency + id: check-consistency + run: | + # Set the issue header + issue="\ + # i18n Contents Consistency Issue\\n\ + \\n\ + The following files may have consistency issues with the English version. Please check and update the files.\\n\ + \\n\ + This issue is created when there is an update to content/en. It compares the git update history to let you know what updates are overdue. The issue should be closed when the update is complete.\\n" + + for file in $(find patterns/2-structured -name '*.md'); do + + # Get the translated file name and check if it exists + i18n_filename=$(echo "$file" | sed 's/patterns\/2-structured/translation\/${{matrix.language}}\/patterns/g') + if [[ ! -e "$i18n_filename" ]]; then + continue + fi + echo $file + echo $i18n_filename + # Loop through all the files in the English directory + # Get the last updated date of the original file and the translated file + original_updated_at=$(date -d "$(git log -1 --format=%cd --date=iso $file)" +%s) + i18n_content_updated_at=$(date -d "$(git log -1 --format=%cd --date=iso $i18n_filename)" +%s) + + # print the last updated date of the original file and the translated file + + # Check if the translated file is updated after the original file + if [[ $(($original_updated_at - $i18n_content_updated_at)) -ge 1 ]]; then + # Get the title of the content + content_header=$(echo "$(cat "$file")" | grep -E '^title+' | sort -r | head -n1) + content_title=$(echo "$content_header" | sed 's/title: //g') + + # Get the days since the translated file is overdue + days_since_overdue_updates=$(($(( $(date +%s) - $original_updated_at))/ 60 / 60 / 24)) + # Get the diff between the original file and the translated file + original_last_update_hash=$(git log -1 --format=%H $file) + # Get the parent hash of the original last update hash + parent_hash=$(git log -1 --format=%P $original_last_update_hash) + # Get the diff between the original file and the translated file + + result=$(echo "$(git diff ${parent_hash} HEAD $file)" | sed '1,4 s/^/# /') + echo -e "$result" + + # Add the contents to the issue.md file + issue+="
$content_title ($file)\\n\\n" + issue+="- Original File(en): [$file](https://github.com/$GITHUB_REPOSITORY/blob/master/$file)\\n" + issue+="- Translated File(${{matrix.language}}): [$i18n_filename](https://github.com/$GITHUB_REPOSITORY/blob/master/$i18n_filename)\\n" + issue+="- [Diff on GitHub](https://github.com/yuhattor/innersourcecommons.org/compare/$i18n_last_update_hash...$original_last_update_hash)\\n" + issue+="- Days since overdue updates: $days_since_overdue_updates days\\n" + issue+="\`\`\`diff\\n" + issue+="$result" + issue+="\\n\`\`\`\\n" + issue+="
\\n" + echo -e "$issue" >> issue.md + issue="" + fi + done + - name: Create Issue + run: | + # Declare the flags + declare -A flags=( + ["ja"]="🇯🇵 Japanese" + ["zh"]="🇨🇳 Chinese" + ) + + # Set the issue title + issue_title="${flags[${{matrix.language}}]}: Content Consistency Issue" + + # Get the existing issue ID + existing_issue_id=$(gh issue list -S "state:open type:issue title:$issue_title" | cut -f1) + + # If the issue.md file exists, create a new issue or comment on the existing issue + if [ -f issue.md ]; then + if expr "$existing_issue_id" : '^[0-9]*$' >/dev/null; then + gh issue comment "$existing_issue_id" -F issue.md -R $GITHUB_REPOSITORY + else + gh issue create -t "$issue_title" -F issue.md -R $GITHUB_REPOSITORY -l "Type - Translation" + fi + fi + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/lint-patterns.yml b/.github/workflows/lint-patterns.yml index a2bb125ec..408619ea7 100644 --- a/.github/workflows/lint-patterns.yml +++ b/.github/workflows/lint-patterns.yml @@ -1,4 +1,6 @@ # from: https://github.com/marketplace/actions/markdown-linting-action +# To test this locally, switch to the root of the repo and run: +# markdownlint -r config/lint/pattern-template.js -c config/lint/pattern-template.yml patterns/2-structured/*.md patterns/2-structured/project-setup/*.md patterns/3-validated/*.md name: Pattern Syntax Validation on: @@ -8,7 +10,7 @@ on: pull_request: paths: - ".github/workflows/lint-patterns.yml" - - "lint/*" + - ".github/lint-pattern-syntax/*" - "patterns/2-structured/*.md" - "patterns/2-structured/project-setup/*.md" - "patterns/3-validated/*.md" @@ -23,6 +25,6 @@ jobs: - name: Lint pattern files (markdown) uses: avto-dev/markdown-lint@v1 with: - rules: './lint/pattern-template.js' - config: './lint/pattern-template.yml' + rules: './.github/lint-pattern-syntax/pattern-template.js' + config: './.github/lint-pattern-syntax/pattern-template.yml' args: 'patterns/2-structured/*.md patterns/2-structured/project-setup/*.md patterns/3-validated/*.md' diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 000000000..870c1097f --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,26 @@ +name: Spelling & Styles + +on: + push: + branches: + - main + paths: + - '**.md' + pull_request: + branches: + - main + +jobs: + vale: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Vale Linting + uses: errata-ai/vale-action@reviewdog + with: + files: '["patterns/2-structured/", "patterns/3-validated/"]' + vale_flags: "--glob=*.md" + filter_mode: added + debug: true diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..3f936ba7d --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# We want to ignore our vale StylesPath +.github/vale/* diff --git a/.lycheeignore b/.lycheeignore index 33c6a3f7f..473a94f74 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -4,8 +4,9 @@ https://example.com/link/to/your/trusted/committer/documentation.md https://github.com/rcs/rcs-viewer/pull/81 http://creativecommons.org/licenses https://isc-inviter.herokuapp.com +https://innersourcecommons-inviter.herokuapp.com fearlesschangepatterns.com https://ulir.ul.ie/bitstream/handle/10344/4443/Stol_2014_inner.pdf .*@andrew.clegg.* https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a -https://innersourcecommons-inviter.herokuapp.com +https://www.chathamhouse.org/about-us/chatham-house-rule \ No newline at end of file diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..142bd22dd --- /dev/null +++ b/.vale.ini @@ -0,0 +1,12 @@ +StylesPath = .github/vale +MinAlertLevel = suggestion + +Packages = https://github.com/InnerSourceCommons/isc-styles/releases/latest/download/ISC.zip + +Vocab = Base + +[*] +BasedOnStyles = ISC + +; If you **don't** want to check for the correct spelling of "InnerSource", comment this in +; ISC.InnerSource = NO diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fdfbefef..8d58bb70e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ We are happy to support you in contributing to the InnerSource patterns or to ju You can best reach out to us **via Slack**: -Join the InnerSource Commons [Slack instance](https://isc-inviter.herokuapp.com/) and enter the `#innersource-patterns` channel there. +Join the InnerSource Commons [Slack instance](https://innersourcecommons.org/slack) and enter the `#innersource-patterns` channel there. ## License of Contributions diff --git a/README.md b/README.md index df64936f4..5dece7439 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ Our mission * [Core Team](patterns/2-structured/core-team.md) - *Even when an InnerSource project is widely needed, contributions and usage may be hindered because the project is difficult to work with. Establish a core team that is dedicated to take care of the project's fundamental items. Their work enables contributors to add and use the features that provide value to their scenarios.* * [Document your Guiding Principles](patterns/2-structured/document-your-guiding-principles.md) - *The usual InnerSource explanation of "applying open source best practices inside an organisation" does not work well with people lacking an open source background. As a remedy the most important principles of InnerSource get documented and published widely.* * [Extensions for Sustainable Growth](/patterns/2-structured/extensions-for-sustainable-growth.md) - *An InnerSource project is receiving too many contributions, making maintenance difficult. By offering an extension mechanism outside of the core project, the maintainers enable scaling of project capabilities with minimal cost and maintenance overhead.* +* [Standard Release Process](patterns/2-structured/release-process.md) - *Teams may hesitate to adopt an InnerSource project if they are unsure of its maturity. To address this, consistent release notes and published artifacts are crucial. These practices showcase a strong dedication to the project, instilling confidence and assuring users of ongoing commitment to sustainable and well-managed software.* * [Group Support](patterns/2-structured/group-support.md) - *What happens if a team or individual no longer supports an InnerSource project? Keep the project alive by forming a group of interested individuals.* ### Maturity Level 1: Initial @@ -66,7 +67,7 @@ Our mission * [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.* +* [InnerSource Portal - Hygiene](patterns/1-initial/innersource-portal-hygiene.md) - *Allow generation of an official badge for projects intending to be recognized 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.* @@ -74,10 +75,9 @@ Our mission * [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.* +* [InnerSource Guidance Group](patterns/1-initial/innersource-guidance-group.md) - *A highly divergent set of development standards in different teams can slow down collaboration between 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 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 behavior visible removes ambiguity. Writing a contributions document creates a natural way to evolve ownership.* * [Overcoming the Not-Invented-Here Mindset](/patterns/1-initial/not-invented-here.md) - *Perfectly good solutions are being rejected because of "Not Invented Here" (NIH). Engineers and their managers will choose to implement functionality themselves first, even if an alternative exists. A shift towards a culture of "Proudly Found Elsewhere" can help reduce the negative impact of NIH.* * [Balancing Openness and Security](/patterns/1-initial/balancing-openness-and-security.md) - *While InnerSource flourishes in environments with a high degree of shared code, Security/Legal prefers the limitation of source code access to only those that need it. By making Security/Legal part of the team, introducing explicit sharing levels and security policies for shared repositories, as well as defining what qualifies as sensitive information, code sharing can be facilitated while minimizing the associated risks.* * [Crossing the InnerSource Chasm](/patterns/1-initial/crossing-chasm.md) - *Early InnerSource experiments have been successful. Methods that were successful convincing early teams stop working though when scaling the initiative. This chasm can be crossed by using different methods to reach people at different stages of the innovation curve.* diff --git a/book/en/toc.md b/book/en/toc.md index 94183385e..6a0999c44 100644 --- a/book/en/toc.md +++ b/book/en/toc.md @@ -26,7 +26,7 @@ Instead edit toc_template.md * [Core Team](../../patterns/2-structured/core-team.md) - Even when an InnerSource project is widely needed, contributions and usage may be hindered because the project is difficult to work with. Establish a core team that is dedicated to take care of the project's fundamental items. Their work enables contributors to add and use the features that provide value to their scenarios. * [Cross-Team Project Valuation](../../patterns/2-structured/crossteam-project-valuation.md) - It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it. * [Dedicated Community Leader](../../patterns/2-structured/dedicated-community-leader.md) - Select people with both communications and technical skills to lead the communities to ensure success in starting an InnerSource initiative. -* [Document your Guiding Principles](../../patterns/2-structured/document-your-guiding-principles.md) - The usual InnerSource explanation of "applying open source best practices inside an organisation" does not work well with people lacking an open source background. As a remedy the most important principles of InnerSource get documented and published widely. +* [Document your Guiding Principles](../../patterns/2-structured/document-your-guiding-principles.md) - The usual InnerSource explanation of "applying open source best practices inside an organization" does not work well with people lacking an open source background. As a remedy the most important principles of InnerSource get documented and published widely. * [Extensions for Sustainable Growth](../../patterns/2-structured/extensions-for-sustainable-growth.md) - An InnerSource project is receiving too many contributions, making maintenance difficult. By offering an extension mechanism outside of the core project, the maintainers enable scaling of project capabilities with minimal cost and maintenance overhead. * [Gig Marketplace](../../patterns/2-structured/gig-marketplace.md) - Establish a marketplace by creating an intranet website that lists specific InnerSource project needs as "Gigs" with explicit time and skill requirements. This will enable managers to better understand their employee’s time commitment and professional benefits thereby increasing the likelihood of garnering approval to make InnerSource contributions. * [Group Support](../../patterns/2-structured/group-support.md) - What happens if a team or individual no longer supports an InnerSource project? Keep the project alive by forming a group of interested individuals. @@ -36,9 +36,10 @@ Instead edit toc_template.md * [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. +* [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 familiarize 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. +* [Standard Release Process](../../patterns/2-structured/release-process.md) - Teams may hesitate to adopt an InnerSource project if they are unsure of its maturity. To address this, consistent release notes and published artifacts are crucial. These practices showcase a strong dedication to the project, instilling confidence and assuring users of ongoing commitment to sustainable and well-managed software. * [Start as an Experiment](../../patterns/2-structured/start-as-experiment.md) - Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative. * [Transparent Cross-Team Decision Making using RFCs](../../patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md) - InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties. * [Trusted Committer](../../patterns/2-structured/trusted-committer.md) - Many InnerSource projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations, project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions. diff --git a/meta/FAQ.md b/meta/FAQ.md index 9e39ab137..084afc5b4 100644 --- a/meta/FAQ.md +++ b/meta/FAQ.md @@ -17,5 +17,5 @@ This is a list of frequently asked questions about InnerSource Patterns. ## I'd like to consult with the InnerSource Patterns community; do I need to have participating members sign NDAs? -* 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. +* The vast majority of InnerSource Patterns meetings and all conversations in the InnerSource Commons [Slack](https://innersourcecommons.org/slack) are held under the [Chatham House Rule](https://www.chathamhouse.org/about-us/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 f2e801aef..f478310dd 100644 --- a/meta/README.md +++ b/meta/README.md @@ -12,6 +12,7 @@ The topics below cover information about how we define, operate, and upkeep this * [Style Guide](./pattern-style-guide.md) - Recommended conventions to use when writing patterns * [Glossary](./glossary.md) - Defines essential terms that are commonly used when writing new patterns. * [Board Reports](./boardreports) - The Patterns Working Group submits a report to the Board of the InnerSource Commons Foundation on a quarterly basis. This folder contains all reports that the Patterns Working Group has created. +* [Scripts](./scripts) - Scripts that help us with the maintenance of our patterns. ## Unfinished documentation diff --git a/meta/boardreports/2023-02.md b/meta/boardreports/2023-02.md index d9945fd74..b5deb781f 100644 --- a/meta/boardreports/2023-02.md +++ b/meta/boardreports/2023-02.md @@ -2,7 +2,7 @@ ## Meta -* Reporting Period: November 1st, 2022 - January 31st, 2022 +* Reporting Period: November 1st, 2022 - January 31st, 2023 * [merged PRs](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls?q=is%3Apr+closed%3A2022-11-01..2023-01-31+is%3Amerged) * [opened issues](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues?q=is%3Aissue+created%3A2022-11-01..2023-01-31+is%3Aopen) diff --git a/meta/boardreports/2023-05.md b/meta/boardreports/2023-05.md new file mode 100644 index 000000000..74b7db5d1 --- /dev/null +++ b/meta/boardreports/2023-05.md @@ -0,0 +1,109 @@ +# InnerSource Patterns WG - Report for Board Meeting 2023-05 + +## Meta + +* Reporting Period: 2023-02..2023-04 +* [merged PRs](https://github.com/InnerSourceCommons/InnerSourcePatterns/pulls?q=is%3Apr+closed%3A2023-02..2023-04+is%3Amerged) +* [opened issues](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues?q=is%3Aissue+created%3A2023-02..2023-04+is%3Aopen) + +## Engagement + +The [patterns book] is the way InnerSource practices are captured and shared. Recent web analytics: + +* stable traffic on the patterns book (tracking_id: `G-QL1S8MW5D9`) + * 18,361 views total (previous report was 12,143 page) + * that is 50% more traffic, so quite significant! + * not sure where the increase in traffic comes from (didn't have time for a deep-dive) +* Most popular patterns: + * Core Team + * 30 Day Warranty + * InnerSource Portal + * Common Requirements + * Maturity Model +* traffic for translations: + * Japanese - 979 views total (somewhat continuous traffic but with spikes - probably around events of the Japanese community) + * Chinese - 545 views total (most traffic around the time when the book was released at end of 2023/01) + +## Changes + +Changes are contributed via the [InnerSourcePatterns] repository: + +* new visual and other improvements for the [Communication Tooling](https://patterns.innersourcecommons.org/p/communication-tooling) pattern - thank you @spier +* adding known instances to various patterns (BBVA, GitHub, Bosch) - thank you @rahermur, @zkoppert, @gruetter +* improvements to [Modular Code](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/modular-code.md) pattern. - thank you @fioddor + * This is a case of a pattern that is around for years and still did not make it into our book. We suspect that many orgs are using this approach and might not even consider this an enabler for InnerSource. Might be too obvious! We have filed an issue to improve the pattern further and get it published in our book. So please [contribute](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/529)! +* New **Structured** patterns: + * [Group Support](https://patterns.innersourcecommons.org/p/group-support) - great work @rrrutledge +* New **Initial** patterns: + * none +* Last [Trusted Committer](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/TRUSTED-COMMITTERS.md) added was [@yuhattor](https://github.com/yuhattor) (added 2022-07-21) +* Trusted Committer candidates in the pipeline: No + +## Next Goals (same as previous Board report) + +The overall goals of this group are: + +1. Increase number of people consuming the patterns. ("easier to discover", pattern of month, categories) +2. Increase the number and quality of patterns. + 1. Increase the number of people thinking to contribute. ("patterns in wild", "known instances") + 2. Increase probability of successful contribution. ("reduce review time", "lower barrier of entry") + 3. Optimise the existing content. (level-up more patterns, "known instances" again) + +All goals will be progressed but we are prioritising effort towards 2.iii. + +Specifically we want to get existing **Initial (L1)** patterns improved to **Structured (L2)**, so that we can publish them in the book. + +We had a [discussion](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/486#discussion_r1029921121) about this and created a short-list of those patterns (details below). + +We now have a [script](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/scripts/find_upgradeable_patterns.rb) that identifies patterns that could be upgrade, based on the number of Known Instances only: + +``` +$ ruby find_upgradeable_patterns.rb +## Initial => Structured +## 1-Initial patterns primed for upgrade to 2-Structured (based on Known Instances only) +1 | ../../patterns/1-initial/innersource-guidance-group.md +1 | ../../patterns/1-initial/innersource-customer-interview-questions.md +2 | ../../patterns/1-initial/balancing-openness-and-security.md +1 | ../../patterns/1-initial/source-code-inventory.md +1 | ../../patterns/1-initial/incubator-pipeline.md +1 | ../../patterns/1-initial/include-product-owners.md +1 | ../../patterns/1-initial/introducing-metrics-in-innersource.md +1 | ../../patterns/1-initial/modular-code.md +1 | ../../patterns/1-initial/contained-innersource.md +1 | ../../patterns/1-initial/transitioning-contractor-code-to-innersource-model.md +1 | ../../patterns/1-initial/governance-levels.md + +## Structured => Validated +## 2-Structured patterns primed for upgrade to 3-Validated (based on Known Instances only) +3 | ../../patterns/2-structured/30-day-warranty.md +5 | ../../patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md +3 | ../../patterns/2-structured/document-your-guiding-principles.md +4 | ../../patterns/2-structured/trusted-committer.md +3 | ../../patterns/2-structured/core-team.md +3 | ../../patterns/2-structured/maturity-model.md +5 | ../../patterns/2-structured/innersource-portal.md +3 | ../../patterns/2-structured/gig-marketplace.md +3 | ../../patterns/2-structured/project-setup/base-documentation.md +3 | ../../patterns/2-structured/project-setup/communication-tooling.md +``` + +### Shortlisted Patterns + +Here you find more detail about the possible execution of this approach. +It is more information than what the Board needs. It may however help you to understand how we are reasoning about our patterns. + +We identified these patterns as "low-hanging fruits", as they contain a **Known Instance** already, and that info is often hard to get. + +We believe we can contact the respective authors/organizations, and ask them to review the patterns against the [Structured (L2) Requirements](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/contributor-handbook.md#requirements-level-2---structured). The upside for those orgs is to get their pattern (and brand) published in our book. + +We expect that with one round of review (or rather a single PR) we can get these patterns published in our book. + +* **(in progress)** (Comcast) [release-process.md](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/release-process.md) - We kept this pattern in Initial to give the community time to review/harden this pattern before it goes into the book. - See [#524](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/524) +* **(in progress)** (Flutter, Europace) [governance-levels.md](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/governance-levels.md) - Proposed by Europace (Isabel) but further improved by Rob. +* (??? Tim Yao, Georg Grütter) [contained-innersource.md](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/contained-innersource.md) - This pattern has been around for a long time. It can try to contact the two authors and see if they want to bring it over the finish line. +* (Philips) [source-code-inventory.md](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/source-code-inventory.md) +* (Philips, Verizon) [balancing-openness-and-security.md](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/balancing-openness-and-security.md) +* (GitHub) [transitioning-contractor-code-to-innersource-model.md](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/patterns/1-initial/transitioning-contractor-code-to-innersource-model.md) + +[patterns book]: https://patterns.innersourcecommons.org/ +[InnerSourcePatterns]: https://github.com/InnerSourceCommons/InnerSourcePatterns/ diff --git a/meta/contributor-handbook.md b/meta/contributor-handbook.md index ffb60ad9d..592bfd160 100644 --- a/meta/contributor-handbook.md +++ b/meta/contributor-handbook.md @@ -47,6 +47,7 @@ To achieve a given maturity level, a pattern has to satisfy the requirements for - The pattern links to related patterns of this level or higher. - Links from the pattern to outside resources are working and are referencing a trusted resource - whether links are working is verified by [Check: Links](https://github.com/InnerSourceCommons/InnerSourcePatterns/actions/workflows/link-checker.yml) - The pattern is added to at least one phase of the [InnerSource Program Mind Map](../pattern-categorization/README.md). + - Spelling & Styles checks pass - see [Check: Spelling & Styles](https://github.com/InnerSourceCommons/InnerSourcePatterns/actions/workflows/vale.yml) - Artifacts: - The patterns are stored as markdown files in [/patterns/2-structured][patterns-structured]. @@ -64,7 +65,6 @@ To achieve a given maturity level, a pattern has to satisfy the requirements for - Uses & has no conflicts with working group terminology (defined by [Glossary](glossary.md) / implicit usage) - Fits & has no conflicts with existing patterns (of this maturity level) - Thorough review by at least two [trusted committers](../TRUSTED-COMMITTERS.md) - - Spell Checking passes - *Oops! We have not yet developed this* - Artifacts: - The patterns are stored as markdown files in [/patterns/3-validated][patterns-validated]. diff --git a/meta/pattern-template.md b/meta/pattern-template.md index 703c8778d..0464effe2 100644 --- a/meta/pattern-template.md +++ b/meta/pattern-template.md @@ -75,7 +75,7 @@ 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) +## Acknowledgments (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. diff --git a/meta/scripts/Gemfile b/meta/scripts/Gemfile new file mode 100644 index 000000000..1cd3261e2 --- /dev/null +++ b/meta/scripts/Gemfile @@ -0,0 +1,7 @@ +# frozen_string_literal: true + +source "https://rubygems.org" + +git_source(:github) {|repo_name| "https://github.com/#{repo_name}" } + +gem 'commonmarker' diff --git a/meta/scripts/find_upgradeable_patterns.rb b/meta/scripts/find_upgradeable_patterns.rb new file mode 100644 index 000000000..b80bde4fb --- /dev/null +++ b/meta/scripts/find_upgradeable_patterns.rb @@ -0,0 +1,84 @@ +require 'rubygems' +require 'bundler/setup' +Bundler.require(:default) + +require 'pp' + +# ------------------------------------------------------------------------------------------------------------ +# This script scans all patterns in /patterns/1-initial and /patterns/2-structured. +# Based on the number of Known Instances in the pattern, it suggests which patterns that might be ready to be leveled-up. +# +# The number of Known Instances are only one of the [requirement](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/contributor-handbook.md#requirements-level-2---structured) +# for our patterns to reach the next level. Therefore reading the pattern and the level requirements in detail is still required +# to decide whether or not a pattern can be pushed to the next level. + +# NOTE: This script and `/book/scripts/generate_toc.rb` have some overlap in how they are parsing markdown. +# However the overlap seemed minimal, so I opted not to do any deduplication of code. +# ------------------------------------------------------------------------------------------------------------ + +# Count Known Instances in a pattern +# - return 0 if the section does not exist, or does not contain the expected list structure +# - return +def count_known_instances(file) + section_nodes = collect_section_nodes(file, "Known Instances") + list_nodes = [] + # pick the first list in the "Known Instances" section, and return the number of elements in that list. + # CAUTION: this assumes a certain structure across all patterns. Therefore fairly brittle. + list_nodes = section_nodes.select {|n| n.type == :list} + + known_instances_count = 0 + known_instances_count = list_nodes.first.count if !list_nodes.first.nil? + + return known_instances_count +end + +def collect_section_nodes(file, section_title) + markdown = open(file).readlines().join + doc = CommonMarker.render_doc(markdown) + + title_found = false + section_nodes = [] + + doc.walk do |node| + if node.type == :header + if title_found == false + node.each do |subnode| + if subnode.type == :text and subnode.string_content == section_title + title_found = true + end + end + # stop the recursion once the next header is reached + # TODO: is this correct, or should we check if this is another `##` header, rather than any header? + else + break + end + # once the title has been found, collect all nodes up to the next header + elsif title_found == true + section_nodes << node + end + end + + return section_nodes +end + + +# Main block + +puts "## Initial => Structured" +puts "## 1-Initial patterns primed for upgrade to 2-Structured (based on Known Instances only)" +l1_patterns = Dir["../../patterns/1-initial/*.md"] + +l1_patterns.each do |file| + known_instances_count = count_known_instances(file) + puts "#{known_instances_count} | #{file}" if known_instances_count >= 1 +end + +puts "\n" +puts "## Structured => Validated" +puts "## 2-Structured patterns primed for upgrade to 3-Validated (based on Known Instances only)" +l2_patterns = Dir["../../patterns/2-structured/*.md", "../../patterns/2-structured/project-setup/*.md"] + +l2_patterns.each do |file| + known_instances_count = count_known_instances(file) + puts "#{known_instances_count} | #{file}" if known_instances_count >= 3 +end diff --git a/pattern-categorization/innersource-program-mind-map.html b/pattern-categorization/innersource-program-mind-map.html index 8679b97f0..8555997b1 100644 --- a/pattern-categorization/innersource-program-mind-map.html +++ b/pattern-categorization/innersource-program-mind-map.html @@ -23,6 +23,6 @@ + })(() => window.markmap,null,{"type":"heading","depth":1,"payload":{"lines":[0,1]},"content":"InnerSource Program","children":[{"type":"heading","depth":2,"payload":{"lines":[2,3]},"content":"Begin","children":[{"type":"heading","depth":3,"payload":{"lines":[4,5]},"content":"Program Setup","children":[{"type":"heading","depth":4,"payload":{"lines":[6,7]},"content":"Management hesitates to invest in InnerSource","children":[{"type":"heading","depth":5,"payload":{"lines":[8,9]},"content":"Start as an Experiment"}]},{"type":"heading","depth":4,"payload":{"lines":[10,11]},"content":"Slow community growth hinders InnerSource","children":[{"type":"heading","depth":5,"payload":{"lines":[12,13]},"content":"Dedicated Community Leader"}]},{"type":"heading","depth":4,"payload":{"lines":[14,15]},"content":"InnerSource principles are not intuitive for everybody","children":[{"type":"heading","depth":5,"payload":{"lines":[16,17]},"content":"Document your Guiding Principles"}]}]},{"type":"heading","depth":3,"payload":{"lines":[18,19]},"content":"Project Setup","children":[{"type":"heading","depth":4,"payload":{"lines":[20,21]},"content":"Hard to assess a project quickly","children":[{"type":"heading","depth":5,"payload":{"lines":[22,23]},"content":"Standard Base Documentation"}]},{"type":"heading","depth":4,"payload":{"lines":[24,25]},"content":"Ad-hoc communication hinders project growth","children":[{"type":"heading","depth":5,"payload":{"lines":[26,27]},"content":"Communication Tooling"}]},{"type":"heading","depth":4,"payload":{"lines":[28,29]},"content":"Intransparent roadmap and direction of the project","children":[{"type":"heading","depth":5,"payload":{"lines":[30,31]},"content":"Issue Tracker Use Cases"}]}]}]},{"type":"heading","depth":2,"payload":{"lines":[32,33]},"content":"Adopt","children":[{"type":"heading","depth":3,"payload":{"lines":[34,35]},"content":"Valuation Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[36,37]},"content":"How to measure a project's business value","children":[{"type":"heading","depth":5,"payload":{"lines":[38,39]},"content":"Cross-Team Project Valuation"}]},{"type":"heading","depth":4,"payload":{"lines":[40,41]},"content":"Can we rely on the project for an extended period?","children":[{"type":"heading","depth":5,"payload":{"lines":[42,43]},"content":"Standard Release Process"},{"type":"heading","depth":5,"payload":{"lines":[44,45]},"content":"Standard Base Documentation"}]}]},{"type":"heading","depth":3,"payload":{"lines":[46,47]},"content":"Cultural Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[48,49]},"content":"Unrecognized effort","children":[{"type":"heading","depth":5,"payload":{"lines":[50,51]},"content":"Praise Participants"},{"type":"heading","depth":5,"payload":{"lines":[52,53]},"content":"Trusted Committer"}]}]},{"type":"heading","depth":3,"payload":{"lines":[54,55]},"content":"Technical Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[56,57]},"content":"Not meeting everyone's needs","children":[{"type":"heading","depth":5,"payload":{"lines":[58,59]},"content":"Common Requirements"}]},{"type":"heading","depth":4,"payload":{"lines":[60,61]},"content":"Fear of shared support responsibility","children":[{"type":"heading","depth":5,"payload":{"lines":[62,63]},"content":"Service vs. Library"}]},{"type":"heading","depth":4,"payload":{"lines":[64,65]},"content":"Project is difficult to contribute to and use","children":[{"type":"heading","depth":5,"payload":{"lines":[66,67]},"content":"Core Team"}]}]},{"type":"heading","depth":3,"payload":{"lines":[68,69]},"content":"Organizational Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[70,71]},"content":"Discouragement of contributing resource","children":[{"type":"heading","depth":5,"payload":{"lines":[72,73]},"content":"Contracted Contributor"}]},{"type":"heading","depth":4,"payload":{"lines":[74,75]},"content":"Rejection of accepting contribution","children":[{"type":"heading","depth":5,"payload":{"lines":[76,77]},"content":"30 Day Warranty"}]},{"type":"heading","depth":4,"payload":{"lines":[78,79]},"content":"Radical change of management","children":[{"type":"heading","depth":5,"payload":{"lines":[80,81]},"content":"Review Committee"}]},{"type":"heading","depth":4,"payload":{"lines":[82,83]},"content":"Fear of shared support responsibility","children":[{"type":"heading","depth":5,"payload":{"lines":[84,85]},"content":"Service vs. Library"}]},{"type":"heading","depth":4,"payload":{"lines":[86,87]},"content":"Not enough maintainers to scale","children":[{"type":"heading","depth":5,"payload":{"lines":[88,89]},"content":"Trusted Committer"}]},{"type":"heading","depth":4,"payload":{"lines":[90,91]},"content":"Difficult cross-team coordination","children":[{"type":"heading","depth":5,"payload":{"lines":[92,93]},"content":"Transparent Cross-Team Decision Making using RFCs"}]},{"type":"heading","depth":4,"payload":{"lines":[94,95]},"content":"Project without an owner/maintainer","children":[{"type":"heading","depth":5,"payload":{"lines":[96,97]},"content":"Core Team"},{"type":"heading","depth":5,"payload":{"lines":[98,99]},"content":"Group Support"}]}]},{"type":"heading","depth":3,"payload":{"lines":[100,101]},"content":"Cross Legal Entities Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[102,103]},"content":"Concern on legal liabilities or cross-company accounting","children":[{"type":"heading","depth":5,"payload":{"lines":[104,105]},"content":"InnerSource License"}]}]}]},{"type":"heading","depth":2,"payload":{"lines":[106,107]},"content":"Grow","children":[{"type":"heading","depth":3,"payload":{"lines":[108,109]},"content":"Discovery Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[110,111]},"content":"Can't find matching projects","children":[{"type":"heading","depth":5,"payload":{"lines":[112,113]},"content":"Gig Marketplace"},{"type":"heading","depth":5,"payload":{"lines":[114,115]},"content":"InnerSource Portal"}]},{"type":"heading","depth":4,"payload":{"lines":[116,117]},"content":"Difficult to find active projects","children":[{"type":"heading","depth":5,"payload":{"lines":[118,119]},"content":"Repository Activity Score"}]}]}]},{"type":"heading","depth":2,"payload":{"lines":[120,121]},"content":"Scale","children":[{"type":"heading","depth":3,"payload":{"lines":[122,123]},"content":"Self Education/Improvement Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[124,125]},"content":"Not aware of InnerSource best practices","children":[{"type":"heading","depth":5,"payload":{"lines":[126,127]},"content":"Maturity Model"}]},{"type":"heading","depth":4,"payload":{"lines":[128,129]},"content":"Lack of open source knowledge","children":[{"type":"heading","depth":5,"payload":{"lines":[130,131]},"content":"Document your Guiding Principles"}]}]},{"type":"heading","depth":3,"payload":{"lines":[132,133]},"content":"Technical Challenges","children":[{"type":"heading","depth":4,"payload":{"lines":[134,135]},"content":"Increasing maintenance overhead","children":[{"type":"heading","depth":5,"payload":{"lines":[136,137]},"content":"Extensions for Sustainable Growth"}]}]}]}]},null) diff --git a/pattern-categorization/innersource-program-mind-map.md b/pattern-categorization/innersource-program-mind-map.md index 559167619..9bccd8332 100644 --- a/pattern-categorization/innersource-program-mind-map.md +++ b/pattern-categorization/innersource-program-mind-map.md @@ -38,6 +38,12 @@ ##### [Cross-Team Project Valuation](https://patterns.innersourcecommons.org/p/crossteam-project-valuation) +#### Can we rely on the project for an extended period? + +##### [Standard Release Process](https://patterns.innersourcecommons.org/p/release-process) + +##### [Standard Base Documentation](https://patterns.innersourcecommons.org/p/base-documentation) + ### Cultural Challenges #### Unrecognized effort diff --git a/pattern-categorization/innersource-program-mind-map.png b/pattern-categorization/innersource-program-mind-map.png index b14e57275..fba9de764 100644 Binary files a/pattern-categorization/innersource-program-mind-map.png and b/pattern-categorization/innersource-program-mind-map.png differ diff --git a/pattern-categorization/package-lock.json b/pattern-categorization/package-lock.json index 02b9a6137..d64702418 100644 --- a/pattern-categorization/package-lock.json +++ b/pattern-categorization/package-lock.json @@ -220,9 +220,9 @@ } }, "node_modules/bin-version-check/node_modules/semver": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", - "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==", "bin": { "semver": "bin/semver" } @@ -260,9 +260,9 @@ } }, "node_modules/bin-version/node_modules/semver": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", - "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==", "bin": { "semver": "bin/semver" } @@ -1984,9 +1984,9 @@ } }, "node_modules/make-dir/node_modules/semver": { - "version": "6.3.0", - "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", - "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==", + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", "bin": { "semver": "bin/semver.js" } @@ -2296,9 +2296,9 @@ } }, "node_modules/package-json/node_modules/semver": { - "version": "6.3.0", - "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", - "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==", + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", "bin": { "semver": "bin/semver.js" } @@ -2575,9 +2575,9 @@ "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==" }, "node_modules/semver": { - "version": "7.3.5", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.5.tgz", - "integrity": "sha512-PoeGJYh8HK4BTO/a9Tf6ZG3veo/A7ZVsYrSA6J8ny9nb3B1VrpkuN+z9OE5wfE5p6H4LchYZsegiQgbJD94ZFQ==", + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", "dependencies": { "lru-cache": "^6.0.0" }, @@ -2600,9 +2600,9 @@ } }, "node_modules/semver-diff/node_modules/semver": { - "version": "6.3.0", - "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", - "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==", + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==", "bin": { "semver": "bin/semver.js" } @@ -2627,9 +2627,9 @@ } }, "node_modules/semver-truncate/node_modules/semver": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", - "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==", + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==", "bin": { "semver": "bin/semver" } @@ -3274,9 +3274,9 @@ } }, "semver": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", - "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==" + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==" } } }, @@ -3291,9 +3291,9 @@ }, "dependencies": { "semver": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", - "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==" + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==" } } }, @@ -4579,9 +4579,9 @@ }, "dependencies": { "semver": { - "version": "6.3.0", - "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", - "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==" + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==" } } }, @@ -4807,9 +4807,9 @@ }, "dependencies": { "semver": { - "version": "6.3.0", - "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", - "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==" + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==" } } }, @@ -5024,9 +5024,9 @@ } }, "semver": { - "version": "7.3.5", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.5.tgz", - "integrity": "sha512-PoeGJYh8HK4BTO/a9Tf6ZG3veo/A7ZVsYrSA6J8ny9nb3B1VrpkuN+z9OE5wfE5p6H4LchYZsegiQgbJD94ZFQ==", + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", "requires": { "lru-cache": "^6.0.0" } @@ -5040,9 +5040,9 @@ }, "dependencies": { "semver": { - "version": "6.3.0", - "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.0.tgz", - "integrity": "sha512-b39TBaTSfV6yBrapU89p5fKekE2m/NwnDocOVruQFS1/veMgdzuPcnOM34M6CwxW8jH/lxEa5rBoDeUwu5HHTw==" + "version": "6.3.1", + "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz", + "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==" } } }, @@ -5060,9 +5060,9 @@ }, "dependencies": { "semver": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.1.tgz", - "integrity": "sha512-sauaDf/PZdVgrLTNYHRtpXa1iRiKcaebiKQ1BJdpQlWH2lCvexQdX55snPFyK7QzpudqbCI0qXFfOasHdyNDGQ==" + "version": "5.7.2", + "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz", + "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==" } } }, diff --git a/patterns/1-initial/crossing-chasm.md b/patterns/1-initial/crossing-chasm.md index 5970378bc..3a8320d2c 100644 --- a/patterns/1-initial/crossing-chasm.md +++ b/patterns/1-initial/crossing-chasm.md @@ -35,7 +35,7 @@ instead of running into all of the hurdles that early adopters run into. - The goal is to increase collaboration, reduce duplication, increase knowledge sharing. - Some teams already adopted a lot of InnerSource best practices, often when - doing so they had to fix hurdles within the organisation when adopting a more + doing so they had to fix hurdles within the organization when adopting a more collaborative way of working. - Some associates refuse to invest time in experimenting with new ways of working, preferring a stable environment. diff --git a/patterns/1-initial/discover-your-innersource.md b/patterns/1-initial/discover-your-innersource.md index 926efe67c..f64a75c1a 100644 --- a/patterns/1-initial/discover-your-innersource.md +++ b/patterns/1-initial/discover-your-innersource.md @@ -53,7 +53,7 @@ Make it easy to find the reusable code. * Tool with a central view (but people are more inclined to google externally than look internally) * Concierge service (guide) to help product people find stuff. Might not scale but could be helpful in the beginning. * Need some very visible lighthouse projects that start using inner source components and make positive statements about the inner source program. -* Establish a common, asynchronous communication channel (e.g., like slack or metamorph or yammer) across team boundaries. This might not scale beyond a certain organisation size. It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. Note: having one channel for many users of one tool might be considered an anti-pattern because they can't find it unless they already know about it. +* Establish a common, asynchronous communication channel (e.g., like slack or metamorph or yammer) across team boundaries. This might not scale beyond a certain organization size. It is possible people will start splitting this one channel into multiple channels by topic once traffic gets too high. Note: having one channel for many users of one tool might be considered an anti-pattern because they can't find it unless they already know about it. * Encourage (and reward) owners of reusable code to use the same search engine to continually search for products that are candidates for use and adoption of the reusable code but not currently doing so. * Consider creating a marketplace for marketing InnerSource programs (management can use this mechanism to know which InnerSource projects to fund, but seeing how the marketplace reacts). diff --git a/patterns/1-initial/explicit-shared-ownership.md b/patterns/1-initial/explicit-shared-ownership.md index ce1f06b1d..aadcf36c9 100644 --- a/patterns/1-initial/explicit-shared-ownership.md +++ b/patterns/1-initial/explicit-shared-ownership.md @@ -4,11 +4,11 @@ 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. +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 behavior 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. +An organization 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. diff --git a/patterns/1-initial/governance-levels.md b/patterns/1-initial/governance-levels.md index 5b65d11a1..996ce276b 100644 --- a/patterns/1-initial/governance-levels.md +++ b/patterns/1-initial/governance-levels.md @@ -32,13 +32,13 @@ There are projects on GitHub, published purely for the pleasure of the author wi There are projects where the roadmap is created in-house, hidden from public view. Where commit rights come and go with the contract of the employees of one company (e.g. MongoDB, Elastic, Tensorflow). Users are welcome to submit patches, they will even be mentored through. All development happens in the open, but control and strategy is never shared. This would be the equivalent of stage "Contributions Welcome". -There are projects that share write access, but do not share the power to decide who gets write access next. This applies to everyone who is only a committer at an Apache project. There are projects that are fully shared across multiple independent organisations (e.g. k8s, any Apache project) - those would be "Shared Ownership". +There are projects that share write access, but do not share the power to decide who gets write access next. This applies to everyone who is only a committer at an Apache project. There are projects that are fully shared across multiple independent organizations (e.g. k8s, any Apache project) - those would be "Shared Ownership". -The same levels make sense inside of organisations. +The same levels make sense inside of organizations. ## Context -- InnerSource concepts are established within an organisation with multiple projects and teams adopting InnerSource. +- InnerSource concepts are established within an organization with multiple projects and teams adopting InnerSource. - Internal InnerSource practices are not prescribed in detail. - Teams/projects have the autonomy to optimise for their local circumstances. @@ -51,7 +51,7 @@ The same levels make sense inside of organisations. ## Solution -The solution is to create a universally understood language to describe the InnerSource operating models that are used in your organisation. +The solution is to create a universally understood language to describe the InnerSource operating models that are used in your organization. We define **InnerSource operating model** as a description of how much influence the core development team of a project ist willing to share with contributing teams. Or in other terms, the level of influence a contributing team can gain in the respective project. @@ -59,7 +59,7 @@ The shared language for these InnerSource operating models can be established wi 1. Identify the common recurring InnerSource operating models that exist in your teams and projects. 2. Document each model in detail, and give each a distinctive name. -3. Promote the use of these names to describe projects until the name's meaning is understood across the whole organisation. +3. Promote the use of these names to describe projects until the name's meaning is understood across the whole organization. Examples of common InnerSource operating models (1) are: @@ -77,12 +77,14 @@ Examples of promoting the model names (3) are: ## Resulting Context - Cross team communication occurs efficiently without confusion using terms that are universally understood and centrally documented. -- Organisation leaders understand the nuances within practising InnerSource and make better informed and more precise decisions that are easier to communicate. -- Increased standardisation of InnerSource practices within the organisation as the named and documented building blocks are used by teams as a menu for adoption. +- Organization leaders understand the nuances within practising InnerSource and make better informed and more precise decisions that are easier to communicate. +- Increased standardisation of InnerSource practices within the organization as the named and documented building blocks are used by teams as a menu for adoption. - Teams can adopt InnerSource best practices in a step-by-step way which makes adoption easier and less intimidating. ## Known Instances +* Flutter Entertainment + ![InnerSource Pyramid used by Flutter Entertainment](../../assets/img/flutter-pyramid.svg) Flutter Entertainment define an [InnerSource Pyramid](https://innersource.flutter.com/how/) to describe 3 different InnerSource operating models: Readable Source, Guest Contributions and Maintainers in Multiple Teams. Each name is centrally documented. The use of these names is encouraged via repeated usage, direct training and categorisation of each InnerSource project. diff --git a/patterns/1-initial/incubator-pipeline.md b/patterns/1-initial/incubator-pipeline.md index 557fbf639..6f17bfbdb 100644 --- a/patterns/1-initial/incubator-pipeline.md +++ b/patterns/1-initial/incubator-pipeline.md @@ -60,7 +60,7 @@ This pattern was inspired by things like the Apache Software Foundation's incuba ## Known Instances -Being implemented at U.S. Bank. +* Being implemented at **U.S. Bank**. ## Status diff --git a/patterns/1-initial/innersource-guidance-group.md b/patterns/1-initial/innersource-guidance-group.md index 9b0c55773..9683d3320 100644 --- a/patterns/1-initial/innersource-guidance-group.md +++ b/patterns/1-initial/innersource-guidance-group.md @@ -4,7 +4,7 @@ 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. +A highly divergent set of development standards in different teams can slow down collaboration between these teams. A InnerSource Guidance Group that establishes broad governance and behavioral guidelines can help to reduce these frictions. ## Problem diff --git a/patterns/1-initial/innersource-portal-hygiene.md b/patterns/1-initial/innersource-portal-hygiene.md index 97656ca3b..9ab6392ea 100644 --- a/patterns/1-initial/innersource-portal-hygiene.md +++ b/patterns/1-initial/innersource-portal-hygiene.md @@ -6,7 +6,7 @@ InnerSource Portal - Hygiene Based off the [InnerSource portal](../2-structured/innersource-portal.md) pattern. -Allow generation of an official badge for projects intending to be recognised as InnerSource project within your company. +Allow generation of an official badge for projects intending to be recognized as InnerSource project within your company. This will help users distinguishing InnerSource projects which strive to adhere to InnerSourcing principals from repos that - have been made public by mistake, due to negligence or for ease of discoverability (but do NOT adhere to InnerSource patterns/best practices). Furthermore the badge serves as additional marketing for the InnerSource initiative at your company. @@ -17,7 +17,7 @@ This will help users distinguishing InnerSource projects which strive to adhere ## Context -Large organisation with lots of public repos, not all necessarily meeting the desired innerSource project standard. +Large organization with lots of public repos, not all necessarily meeting the desired innerSource project standard. ## Forces @@ -57,7 +57,7 @@ The last step is for users update there repos `README.md` file to include the ba Query InnerSource projects which have an expired badge. Delete badge file causing the badge to not appear in the repos rendered README anymore. - Notify projects approaching expiry. Query InnerSource projects which have a badge close to expiration. Send a notification to the InnerSource projects code owners, publish an issue to the repo, publish a message in the InnerSource channel on Teams. This should be ample warning to go update the badge. -- Bonus: Notify owners of public repos not registered as InnerSource projects yet to either make their repos private or to consider registering their repo as an innerSource project. This isn't entirely related to hygiene of the InnerSource portal rather general hygiene of all repos in your organisations SCM system. Also servers as excellent marketing and awareness generation for your organisations InnerSource initiative. +- Bonus: Notify owners of public repos not registered as InnerSource projects yet to either make their repos private or to consider registering their repo as an innerSource project. This isn't entirely related to hygiene of the InnerSource portal rather general hygiene of all repos in your organizations SCM system. Also servers as excellent marketing and awareness generation for your organizations InnerSource initiative. ## Resulting Context diff --git a/patterns/1-initial/introducing-metrics-in-innersource.md b/patterns/1-initial/introducing-metrics-in-innersource.md index 3550dd55b..89bbf5056 100644 --- a/patterns/1-initial/introducing-metrics-in-innersource.md +++ b/patterns/1-initial/introducing-metrics-in-innersource.md @@ -92,7 +92,7 @@ Continued monitoring of these metrics will help middle management and developers ## Known Instances -Santander Bank +* **Santander Bank** ## Status diff --git a/patterns/1-initial/not-invented-here.md b/patterns/1-initial/not-invented-here.md index a2657a6ba..0d95788de 100644 --- a/patterns/1-initial/not-invented-here.md +++ b/patterns/1-initial/not-invented-here.md @@ -79,7 +79,7 @@ Companies with software developers :) We suppose that this may also be a more co ## Solutions -* [Going deep into the not-invented-here syndrome](http://blog.hypeinnovation.com/the-not-invented-here-syndrome) touches on this topic, describing a prescription for overcoming the "Not Invented Here" mindset: +* [Going deep into the not-invented-here syndrome](https://www.hypeinnovation.com/blog/the-not-invented-here-syndrome) touches on this topic, describing a prescription for overcoming the "Not Invented Here" mindset: * Acknowledge that the "Not Invented Here" mindset (NIH) exists * Assess the impact of NIH on your innovation efforts. For example, have you missed opportunities? * Build in explicit incentives to overcome NIH @@ -131,5 +131,5 @@ TBD ## References -* Oana-Maria Pop, Hype Innovation Blog: [Does Your Organization Have the Not Invented Here Syndrome?](http://blog.hypeinnovation.com/the-not-invented-here-syndrome) +* Oana-Maria Pop, Hype Innovation Blog: [Does Your Organization Have the Not Invented Here Syndrome?](https://www.hypeinnovation.com/blog/the-not-invented-here-syndrome) * DSM, Open Innovation: [Proudly Found Elsewhere](https://www.youtube.com/watch?v=jNNz9poyKJs) diff --git a/patterns/1-initial/release-process.md b/patterns/1-initial/release-process.md deleted file mode 100644 index e98a02f8a..000000000 --- a/patterns/1-initial/release-process.md +++ /dev/null @@ -1,51 +0,0 @@ -## 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/shared-code-repo-different-from-build-repo.md b/patterns/1-initial/shared-code-repo-different-from-build-repo.md index 9dc473520..eba9748f6 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 @@ -1,6 +1,6 @@ ## Title -Repo for Shared Code Different from Repo the Product Org Uses in its Build +Source Repo different from Deployment Chain ## Patlet @@ -8,7 +8,7 @@ Deal with the overhead of having shared code in a separate repository that isn't ## Problem -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. +The InnerSource code repo is different from the repos used in production builds. This causes friction each time changes are made to the InnerSource repo. ## Context @@ -16,11 +16,15 @@ Shared code is kept in an accessible repository that is different from SCMs used ## Forces -When the shared code is in a separate repository, any use of it could result in forking modifications, leading to complications later when the source is changed by the owning organization. When starting an inner sourcing program, it is possible there are many SCM systems in use; and, frequently, a new SCM is used for the inner sourcing program. Migrating from one SCM to another is not trivial. Since the using organization has a copy, they might not be aware of changes to the shared code. It is difficult and expensive for the using organization to change their automated build process to use a foreign repo. +When the shared code is in a separate repository, any use of it could result in forking modifications, leading to complications later when the source is changed by the owning organization. When starting an InnerSource program, it is possible there are many source control management systems ([SCM](https://en.wikipedia.org/wiki/Version_control)) in use; and, frequently, a new SCM is used for the InnerSource program. Migrating from one SCM to another is not trivial. Since the using organization has a copy, they might not be aware of changes to the shared code. It is difficult and expensive for the using organization to change their automated build process to use a foreign repo. ## Solution -Continuous integration, not only to with testing but also in production (aligns with DevOps). Known marker that shows the code hasn't been modified. Improved communication between teams. Accountability when you screw up; hold people accountable. Publish good stats about the negative implications of errors and processes for making this everyone's problem. +* Continuous integration, not only for testing but also in production (aligns with DevOps). +* Known marker that shows the code hasn't been modified. +* Improved communication between teams. +* Accountability when you screw up; hold people accountable. +* Publish good stats about the negative implications of errors and processes for making this everyone's problem. ## Resulting Context diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md index b1a37d172..7c2ab75c3 100644 --- a/patterns/2-structured/30-day-warranty.md +++ b/patterns/2-structured/30-day-warranty.md @@ -54,7 +54,7 @@ In addition it helps to provide clear [contribution guidelines](./project-setup/ - Cedric Williams -## Acknowledgement +## Acknowledgments - Dirk-Willem van Gulik - Padma Sudarsan diff --git a/patterns/2-structured/common-requirements.md b/patterns/2-structured/common-requirements.md index c13899b92..0381be2b2 100644 --- a/patterns/2-structured/common-requirements.md +++ b/patterns/2-structured/common-requirements.md @@ -56,7 +56,7 @@ A related challenge (and possible new pattern) is a circular story-writing exerc ## Known Instances -* Large telecom provider +* Large telecommunications provider ## Status @@ -66,7 +66,7 @@ A related challenge (and possible new pattern) is a circular story-writing exerc Robert Hanmer -## Acknowledgements +## Acknowledgments * Manrique Lopez * Daniel Izquierdo diff --git a/patterns/2-structured/contracted-contributor.md b/patterns/2-structured/contracted-contributor.md index d36043fc3..0790f6774 100644 --- a/patterns/2-structured/contracted-contributor.md +++ b/patterns/2-structured/contracted-contributor.md @@ -31,12 +31,12 @@ 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. -However, top-level management has not yet empowered or incentivised mid-level +However, top-level management has not yet empowered or incentivized 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 their working time. Cross organizational collaboration is not yet the norm and -line managers usually do not have targets outside of their own organisation. +line managers usually do not have targets outside of their own organization. Contributions to InnerSource projects are expected to be made during working hours, not during free time. @@ -46,7 +46,7 @@ hours, not during free time. - 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 less formally work in InnerSource is managed and organized, 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. @@ -93,7 +93,7 @@ A formal contracting is also beneficial for contributors and communities: - Georg Grütter (Robert Bosch GmbH) -## Acknowledgements +## Acknowledgments - Diogo Fregonese (Robert Bosch GmbH) - Robert Hansel (Robert Bosch GmbH) diff --git a/patterns/2-structured/core-team.md b/patterns/2-structured/core-team.md index 84c6504e0..e62139595 100644 --- a/patterns/2-structured/core-team.md +++ b/patterns/2-structured/core-team.md @@ -20,7 +20,7 @@ This could be due to things like: Some possible causes: * Poor documentation (again). * Frequent bugs. - * Unintuitive setup. + * Nonintuitive setup. ## Story @@ -35,7 +35,7 @@ It's clearly due for an overhaul (e.g. refactoring, testing, documentation, etc. * 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. +* There is not a owner or maintainer who takes responsibility for the project and contribution ecosystem as a whole. ## Forces @@ -53,7 +53,7 @@ Here are some specific examples: * Production bugs * Documentation -* Onboarding tutorials and examples +* On-boarding tutorials and examples * Automated testing * CI/CD * Local environment diff --git a/patterns/2-structured/crossteam-project-valuation.md b/patterns/2-structured/crossteam-project-valuation.md index 1fede7cc2..96b89c8e2 100644 --- a/patterns/2-structured/crossteam-project-valuation.md +++ b/patterns/2-structured/crossteam-project-valuation.md @@ -15,7 +15,7 @@ Here's a data-driven way to represent your project that both articulates its val ## Problem Cross-team projects can potentially have a very large impact on the company yet are difficult to represent in a data-driven fashion. -As a result, it is easy and common to either pursue projects that does not provide real value or to underfund what would otherwise produce great value. +As a result, it is easy and common to either pursue projects that do not provide real value or to underfund what would otherwise produce great value. ## Forces @@ -49,7 +49,7 @@ The idea is for the group of experts to be able to say to each other, "We don't 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 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. +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, hard-coded implementation used just once. ### Formula @@ -58,9 +58,9 @@ Once you have your worst-case bounds you can value your cross-team project outpu ``` [Time Saved] - [Time Invested] -([Count of New Onboardings] * [Cost to Home-Roll] * [Percent Useful Functionality] + [Count of Usages] * [Maintenance Cost Per Use]) - ([Count of New Onboardings] * [Cost to Onboard]) +([Count of New On-boardings] * [Cost to Home-Roll] * [Percent Useful Functionality] + [Count of Usages] * [Maintenance Cost Per Use]) - ([Count of New On-boardings] * [Cost to On-board]) -[Count of New Onboardings] * ([Cost to Home-Roll] * [Percent Useful Functionality] - [Cost to Onboard]) + [Count of Usages] * [Maintenance Cost Per Use] +[Count of New On-boardings] * ([Cost to Home-Roll] * [Percent Useful Functionality] - [Cost to On-board]) + [Count of Usages] * [Maintenance Cost Per Use] ``` ### Commentary @@ -81,7 +81,7 @@ Some may be concerned about the lack of accuracy in this valuation approach. It 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. +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. ## Resulting Context @@ -103,6 +103,6 @@ They will provide a head-and-shoulders improvement in on-the-ground results over * Russ Rutledge -## Acknowledgement +## Acknowledgments * Jeremiah Wright for teaching me to think about cross-team projects as an internal business dealing in the currency of developer time. diff --git a/patterns/2-structured/dedicated-community-leader.md b/patterns/2-structured/dedicated-community-leader.md index 00ed71373..91f3c3d0d 100644 --- a/patterns/2-structured/dedicated-community-leader.md +++ b/patterns/2-structured/dedicated-community-leader.md @@ -58,7 +58,7 @@ Having excellent and dedicated community leaders is a precondition for the succe ## Known Instances -_BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. +* _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding. ## Alias @@ -73,7 +73,7 @@ Dedicated Community Manager - Georg Grütter (Robert Bosch GmbH) - Diogo Fregonese (Robert Bosch GmbH) -## Acknowledgements +## Acknowledgments - Tim Yao - Padma Sudarsan diff --git a/patterns/2-structured/document-your-guiding-principles.md b/patterns/2-structured/document-your-guiding-principles.md index 160d43434..01c423dfb 100644 --- a/patterns/2-structured/document-your-guiding-principles.md +++ b/patterns/2-structured/document-your-guiding-principles.md @@ -4,21 +4,21 @@ Document your Guiding 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. +The usual InnerSource explanation of "applying open source best practices inside an organization" does not work well with people lacking an open source background. As a remedy the most important principles of InnerSource get documented and published widely. ## Problem -The organisation is trying to roll out InnerSource at a larger scale. +The organization 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. +As a result InnerSource adoption in the organization 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. +Early experiments in an organization 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 @@ -32,27 +32,27 @@ as well as a clear path towards achieving these goals. ## 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. +* People lacking open source experience fail to understand what it means to bring open source best practices into the organization. * 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. +Those driving the InnerSource initiative in the organization 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 to teams and individuals by documenting these two areas: -1. **Purpose** - Why does the organisation want to adopt InnerSource? +1. **Purpose** - Why does the organization want to adopt InnerSource? 2. **Principles** - Which InnerSource principles will help to address these challenges? The following sections provide more details about both of these, meant as possible starting points to document them for your organization. -### Why does the organisation want to adopt InnerSource? +### Why does the organization want to adopt InnerSource? -In the past InnerSource has proven to be successful to solve several issues commonly found in organisations. +In the past InnerSource has proven to be successful to solve several issues commonly found in organizations. 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. +Instead of going for generalizations, try to exactly identify the solutions that match the challenges of your organization - preferably with those affected by the change you want to see. Some challenges that others have addressed by following InnerSource best practices: @@ -71,9 +71,9 @@ Once teams understand which problems InnerSource will help them address, the nex Based on basic open source development principles the following guidelines have been proven successful: -(1) Code must be transparently hosted within the organisation +(1) Code must be transparently hosted within the organization -Source code, documentation, data relevant for project development must be available and easy to find for anyone in the organisation. +Source code, documentation, data relevant for project development must be available and easy to find for anyone in the organization. (2) Contributions over feature requests @@ -84,7 +84,7 @@ 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. +With work visible across the entire organization 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 @@ -104,7 +104,7 @@ 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. +2. There are exceptions to the rule of everything being written and accessible to the entire organization: People related discussions as well as security related discussions are sensitive and should not be held in public. (6) Reward Trusted Committership @@ -114,17 +114,21 @@ 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 activities 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. +* Organization members understand which challenges they can address by applying InnerSource best practices. +* Organization members lacking prior open source experience understand the basic values and principles of InnerSource projects. +* Organization members lacking prior open source experience are able to check their daily activities against a set of common established values. +* The organization's development practices become more similar to open source projects thus making it easier for organization members to participate in open source projects. ## Known Instances +* Europace AG +* GitHub +* Robert Bosch GmbH + ### Europace AG -The InnerSource principles listed in the Solution above are mostly based on Europace's experience. -For more details see [Europace InnerSource Prinzipien](https://tech.europace.de/post/europace-inner-source-prinzipien/) (in German). +The InnerSource principles listed in the Solution section above are mostly based on Europace's experience. +See [details](https://tech.europace.de/post/europace-inner-source-prinzipien/) (in German). ### GitHub @@ -202,7 +206,7 @@ Structured * Isabel Drost-Fromm * Georg Grütter -## Acknowledgements +## Acknowledgments * Zack Koppert - for sharing GitHub's approach in the Known Instances diff --git a/patterns/2-structured/feature-owners.md b/patterns/2-structured/feature-owners.md index e972ad55a..2c40c36eb 100644 --- a/patterns/2-structured/feature-owners.md +++ b/patterns/2-structured/feature-owners.md @@ -64,7 +64,7 @@ Feature owners responsibilities: * Manoj Gawande -## Acknowledgement +## Acknowledgments * Dinesh Ramadoss * Amit Chauhan diff --git a/patterns/2-structured/innersource-license.md b/patterns/2-structured/innersource-license.md index 37e199bdf..1183ea45a 100644 --- a/patterns/2-structured/innersource-license.md +++ b/patterns/2-structured/innersource-license.md @@ -37,7 +37,7 @@ At the time of sharing the source code, it can not be reliably predicted what th Creating an **InnerSource License** customized to the needs of the organization in question (and their legal entities). This license needs to be generic enough to be applied to the most important inter-company relationships. -It is important to write the InnerSource License such that it truly allows for OpenSource-like collaborations across the boundaries of the involved legal entities. Therefore the 4 freedoms of free software should be integrated into the license. +It is important to write the InnerSource License such that it truly allows for open source style collaboration across the boundaries of the involved legal entities. Therefore the 4 freedoms of free software should be integrated into the license. The License is written as a formal legal document, and can be used as part of contracts between the legal entities to govern the code sharing agreements. diff --git a/patterns/2-structured/innersource-portal.md b/patterns/2-structured/innersource-portal.md index 88c640a35..141d2fbb7 100644 --- a/patterns/2-structured/innersource-portal.md +++ b/patterns/2-structured/innersource-portal.md @@ -69,15 +69,15 @@ A [reference implementation](https://github.com/SAP/project-portal-for-innersour * **Elbit Systems** has used this pattern and added gamification on top. * [Gamification As Means of Cultural Change and InnerSource Engagement Booster](https://www.oreilly.com/library/view/oscon-2018-/9781492026075/video321579.html) | Shelly Nizri | OSCON 2018 - Portland, Oregon * Of Islands, Monsters & InnerSource [(slides)](https://docs.google.com/presentation/d/1P1OCEK9B6eSrVRUclVWY6meSI-qHOBjM_UAPNvCZamU/edit#slide=id.p15), [(video)](https://drive.google.com/file/d/1pM89uHMn0vhE3ayFJDGYcCO8R0tAXXZD/view?usp=drivesdk) | InnerSource Spring Summit 2019 (Galway, Ireland) - * The code realizing this platform has been open sourced and is available at [gitlab.com/gilda2](https://gitlab.com/gilda2) + * The [code](https://gitlab.com/gilda2) realizing this platform has been open sourced. * **American Airlines** promotes InnerSource projects via an [internal InnerSource Marketplace](https://tech.aa.com/2020-10-30-innersource/). Similarly to SAP, projects self-register by adding `innersource` as a GitHub topic. Projects are searchable and filterable by language, topics, number of open issues, etc. * **Banco Santander** has created a public portal called "Santander ONE Europe InnerSource Community" to support and increase InnerSource adoption. In addition to the catalog of projects the portal includes relevant content such as documentation, way of working, news, and events. ![Santander InnerSource Portal](../../assets/img/santander_portal.png "Banco Santander InnerSource Portal") -* **Airbus** deployed the [SAP portal](https://github.com/SAP/project-portal-for-innersource) with minor modifications to match Airbus graphical identity. In addition, the [Python crawler](https://github.com/zkoppert/innersource-crawler) was patched to work with GitHub Enterprise instances. - +* **Airbus** used the [SAP Portal](https://github.com/SAP/project-portal-for-innersource) as a Proof of Concept. It is now using the [Bazaar plugin](https://github.com/backstage/backstage/blob/master/plugins/bazaar/README.md) of [Backstage](https://backstage.io) as the latter became the official developer experience tool internally. It provides a convenient self-registering capability for all the divisions. * **Mercado Libre** use an instance of the [SAP portal](https://github.com/SAP/project-portal-for-innersource) to discover existing InnerSource projects within the organization. +* **Mercedes-Benz** is [using](https://opensource.mercedes-benz.com/news/sponsor_innersource_commonsoss) the SAP reference implementation mentioned above for their InnerSource Portal. ## References @@ -91,7 +91,7 @@ A [reference implementation](https://github.com/SAP/project-portal-for-innersour * Stephen McCall -## Acknowledgements +## Acknowledgments * Shelly Nizri * Melinda Malmgren diff --git a/patterns/2-structured/maturity-model.md b/patterns/2-structured/maturity-model.md index e9ce8c070..8e410625e 100644 --- a/patterns/2-structured/maturity-model.md +++ b/patterns/2-structured/maturity-model.md @@ -96,7 +96,7 @@ When working in host teams mistakes will automatically be widely visible. In ord For silos to be reduced colleagues need to be comfortable sharing feedback openly. One easy way to support that is to use the same communication principles across hierarchies. -Ideally you will end up with proper communication channels that are known by anyone in the organization - with channels focussed on different goals (announcements, user support, development channels, infra discussions, etc.). Some of the best practices you will establish as your InnerSource projects mature: Adoption of netiquette guidelines, opening a proven set of standard channels (which are being archived, publicly accessible, searchable) for each new InnerSource project. +Ideally you will end up with proper communication channels that are known by anyone in the organization - with channels focused on different goals (announcements, user support, development channels, infra discussions, etc.). Some of the best practices you will establish as your InnerSource projects mature: Adoption of netiquette guidelines, opening a proven set of standard channels (which are being archived, publicly accessible, searchable) for each new InnerSource project. * CF-0: There are no processes nor established channels. Some members of the organization share materials via private channels or discussions. * CF-1: The organization is in the process of establishing internal guidelines and channels for encouraging diverse points of view about company/departmental decisions, so that anyone belonging to the organization can use them. Some members of the organization share decision-making materials informally using unofficial platforms. Leaders maintain at least one clear and direct channel for organization members to share opinions constructively on some matters relevant to their work. @@ -139,12 +139,12 @@ Having a baseline of shared values makes it easier to work across team boundarie * SP-0: No sharing culture nor written policies. * SP-1: Some members of the organization unite to define values and principles, but are not clearly supported when they do. -* SP-2: Members of the organization collectively document shared visions and agreements like mission statements and codes of conduct, make them easily accessible, and reference them often. Onboarding materials and orientation rituals provide adequate context for helping new members understand how the organization will benefit from their contributions. +* SP-2: Members of the organization collectively document shared visions and agreements like mission statements and codes of conduct, make them easily accessible, and reference them often. On-boarding materials and orientation rituals provide adequate context for helping new members understand how the organization will benefit from their contributions. * SP-3: Shared values and principles inform decision-making, conflict resolution, and assessment processes among members of the organization, who reference these values and principles consistently in both verbal and written formats. **Feel part of the Organization** -One of the possible reasons for introducing InnerSource into organisations can be increased engagement. This point tracks how engagement is changing while adopting InnerSource. +One of the possible reasons for introducing InnerSource into organizations can be increased engagement. This point tracks how engagement is changing while adopting InnerSource. * PA-0: Low engagement, no collaboration and people do not feel comfortable sharing with others. * PA-1: Members of the organization feel comfortable sharing their thoughts and opinions without fear of retribution, but only in familiar domains. People understand that the best ideas win, and leadership responsibilities accrue to people with histories of contribution and commitment. @@ -164,7 +164,7 @@ In order to drive adoption, extrinsic motivators can be used to increase cross t **Monitoring Policies** -InnerSource projects need a means for self assessment. Metrics can be one aspect to facilitate this assessment. Also, in organisations with a mature InnerSource adoption level we expect adoption of the method to be tracked based on clear, agreed upon metrics. +InnerSource projects need a means for self assessment. Metrics can be one aspect to facilitate this assessment. Also, in organizations with a mature InnerSource adoption level we expect adoption of the method to be tracked based on clear, agreed upon metrics. * 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. @@ -175,7 +175,7 @@ InnerSource projects need a means for self assessment. Metrics can be one aspect Not only should feature development be owned by InnerSource teams - support and maintenance is also part of the teams core tasks. -* SM-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. +* SM-0: Support given by the core development or support team. A business contract guaranties the support. There is no knowledge about the product outside the team. * SM-1: There are rules and regulations to formalize the support on the product, given by a dedicated supporting team. * SM-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). * SM-3: There are rules and regulations to formalize the support on the product, given by a mature community. @@ -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 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-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 development 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 @@ -221,7 +221,7 @@ long term. * Jorge * Nerea -## Acknowledgements +## Acknowledgments * Alexander Andrade (special thanks for the spelling fixes) diff --git a/patterns/2-structured/praise-participants.md b/patterns/2-structured/praise-participants.md index 27dc7aecc..10271045b 100644 --- a/patterns/2-structured/praise-participants.md +++ b/patterns/2-structured/praise-participants.md @@ -77,7 +77,7 @@ Overdoing it may feel insincere and mechanical and defeat your purpose in reachi * Russ Rutledge -## Acknowledgements +## Acknowledgments * [Todd Lisonbee](https://github.com/tlisonbee) for encouraging to "keep it real". * [Isabel Drost-Fromm](https://github.com/MaineC) for [this extra explanation](https://youtu.be/h3MPewsk5PU?t=357) of a "qualified" thank you. diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/project-setup/base-documentation.md index 746c87079..7c726f0b7 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/project-setup/base-documentation.md @@ -12,7 +12,7 @@ the most common questions on their own. ## Problem -A team wants to share either a freshly started or a pre-existing project with +A team wants to share either a freshly started or a preexisting project with the wider organization and receive contributions to it. Potential contributors often are lost: They are failing to identify the team's preferred communication channels. They have trouble quickly making a judgment about whether a new @@ -109,7 +109,7 @@ started right away: [README-template.md](templates/README-template.md) and * Europace AG - See blog post [InnerSource: Adding base documentation](https://tech.europace.de/post/innersource-base-documentation/) * Paypal Inc. -* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBNUTING, CODING_GUIDELINES, etc). +* Mercado Libre - create a documentation site that contains how to get started with InnerSource and also define the basic artifacts that a repository must have to be InnerSource (README, CONTRIBUTING, CODING_GUIDELINES, etc). ## Authors diff --git a/patterns/2-structured/project-setup/communication-tooling.md b/patterns/2-structured/project-setup/communication-tooling.md index 6e6af3612..67ad6b844 100644 --- a/patterns/2-structured/project-setup/communication-tooling.md +++ b/patterns/2-structured/project-setup/communication-tooling.md @@ -10,7 +10,7 @@ By consistently using asynchronous communication tooling, the project makes disc ## Problem A team is open to receiving contributions from downstream users of their -component. Coordination and communication happens in an ad-hoc fashion though +component. Coordination and communication happens in an ad hoc fashion though leading to incoherent information being shared, delays in answers received, contributors pinging multiple host team members before receiving a definitive answer. @@ -82,7 +82,7 @@ to a lower need to repeat explanations. Isabel Drost-Fromm -## Acknowledgement +## Acknowledgment Sebastian Spier (for the visual) diff --git a/patterns/2-structured/project-setup/templates/COMMUNICATION-template.md b/patterns/2-structured/project-setup/templates/COMMUNICATION-template.md new file mode 100644 index 000000000..cf7cc74a8 --- /dev/null +++ b/patterns/2-structured/project-setup/templates/COMMUNICATION-template.md @@ -0,0 +1,73 @@ +# COMMUNICATION.md + +*** +Put an individual COMMUNICATION.md file tailored to the project in each repo. If project repo ownership is transferred to a different team in the future, they need to be able to access and edit documentation related to the project. This includes documentation that outlines the communication processes that users should use to contact the team. + +**Delete top paragraph when this section is filled out.** + +## Team Communication + +Team Slack channel: + +Special Slack Channels: (topic specific and accessible to anyone who would be an external contributor) + +Team Email: + +## How to Contact Us + +The following types of actions can be moved to the appropriate section and more added. + +| Action | (General team contact) | +|--------------------------------|--------------------------| +| Contact Method | (email or slack channel) | +| Bug report | | +| Feature request | | +| Contribution process questions | | +| Merge Requests after submission | | +| Add more here… | | + +| Special Situations: | Direct point of contact (Role) | +|---------------------|--------------------------------| +| Status updates | | +| other | | +| other | | +| Add more here... | | + +## Roles and Responsibilities + +Managers or roles and specific situations they should be contacted for outside the team channel. + +(this is set up this way so that the document can easily be changed if there are new members on the team) + +| Role | Name | Preferred contact method | +|------|------|--------------------------| +| | | | +| | | | +| | | | + +## Outbound Communication + +| Scenarios | When users will receive communication | Stakeholders who will receive | Action - how to receive these communications | +|-----------------------------------------------------------------------------------|--------|----------------|----------| +| Breaking changes (for e.g. any changes to our API or messaging contracts) | | | | +| Extended/planned outages (service downtime for maintenance related activities) | | | | +| Unexpected Outages | | | | +| Traffic specific changes (e.g. team to team, etc.) | | | | +| New Feature rollout | | | | +| As per product guidelines | | | | +| Month end and company wide code freeze | | | | +| Internal team and any other teams who contribute to team project repos | | | | +| Add more… | | | | + +## Documentation Contacts + +Tell how to find the owner, responsible party, or group people should contact if they have questions about documentation in the repo. + +Describe this communication process. + +For example: + +* If you have questions on a specific piece of documentation, you can find the team member responsible for the information by looking here: +* You can contact the responsible party by sending a message in the xyz channel, send them a direct message in chat, email, etc. The individual who last certified the documentation is the responsible party. + +*** diff --git a/patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md b/patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md index f45541a25..a42cd013f 100644 --- a/patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md +++ b/patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md @@ -11,7 +11,7 @@ improving documentation, fixes to bugs, as well as new feature implementations. Add information on how to submit bug reports here. This should include hints about which type of information the project will need in order to reproduce and fix issues. It can also include information on commonly found -mis-configurations that look like bugs. +misconfigurations that look like bugs. Also include information on what contributors can expect in terms of time to first response and process after that. @@ -47,5 +47,5 @@ if that route is open to contributors. This section serves as a reminder to existing and explanation for new Trusted Committers detailing how to add others to the host team. Again ideally this -information is identical for all projects in the organisation so central +information is identical for all projects in the organization so central information can be linked to from here. diff --git a/patterns/2-structured/project-setup/templates/README-template.md b/patterns/2-structured/project-setup/templates/README-template.md index 699283a1b..07fe0def2 100644 --- a/patterns/2-structured/project-setup/templates/README-template.md +++ b/patterns/2-structured/project-setup/templates/README-template.md @@ -43,7 +43,7 @@ communication channels. This is a good place to give credit to Trusted Committers of the project. It's also a good place to include information on what being a Trusted Committer -means for this project - although ideally all projects in an organisation use +means for this project - although ideally all projects in an organization use the same definition that is only linked to from here. The reason to keep the link here is for colleagues who have no or little experience with working in and contributing to InnerSource projects to have a direct link back to company wide diff --git a/patterns/2-structured/release-process.md b/patterns/2-structured/release-process.md new file mode 100644 index 000000000..9ee5188aa --- /dev/null +++ b/patterns/2-structured/release-process.md @@ -0,0 +1,69 @@ +## Title + +Standard Release Process + +## Patlet + +Teams may hesitate to adopt an InnerSource project if they are unsure of its maturity. To address this, consistent release notes and published artifacts are crucial. These practices showcase a strong dedication to the project, instilling confidence and assuring users of ongoing commitment to sustainable and well-managed software. + +## Problem + +When a team is deciding whether to use an InnerSource project, one of their considerations is whether 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 when necessary and has tangible benefits. + +It is common practice for Open Source projects to have versioned releases, with notes documenting breaking changes, and new features 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. + +InnerSource projects that don't have a published artifact or release process reduces trust. Teams won't know when they can expect the next release, when breaking changes are introduced, etc. + +## Context + +Large organizations produce a lot of internal software, much of which could be reused by teams across the company. Operational tooling, software libraries, and infrastructure as code (IaC) modules are common examples of this type of software. Most large organizations, however, don't publish internal software to be consumed by other teams in the company. This can occur either because they are to busy to provide documentation or don't realize the projects value to others. + +An internal or public source repository should be available where source code is stored, but teams lack a process for making software consumable by outside teams. + +As an organization grows and more internal software is written, the value of this pattern grows. + +## Forces + +### Difficult for organizations that don't have a central CI/CD system + +For organizations that don't provide engineers a centralized CI/CD system, automating a build and release process can be challenging. The team may need to stand up their own tool (Jenkins, Drone, etc). Without a CI/CD system, builds and release notes can still be produced, however, it may require a local build of the software and manual upload to whichever tool is hosting build artifacts. + +### Added burden of publishing release notes + +In addition to building your source code, writing release notes can be tedious without the ability to auto-generate a list of git commits. This would be left for someone to do manually, in addition to writing more high level details on a release. + +### Increased difficulty without a location to host artifacts + +If a company does not provide a centralized location for storing build artifacts (jars, npm modules, etc.) and docker images, engineers may be left deciding for themselves where is appropriate to store versioned software. Tools like GitHub provide this for you, however, if a company is not using one of these popular tools, this could pose a burden. + +## Solution + +By providing clear **release notes** and a published artifact you increase people's confidence that you are publishing a quality product that they can rely on. + +The following are key elements to achieve this: + +- A CI/CD pipeline is located within your repository that [automates the release process](https://opensource.guide/best-practices/#use-tools-to-automate-basic-maintenance-tasks) +- Build artifacts are generated by the CI/CD system (binary, docker image, jar, etc) +- Releases are clearly labeled and tagged with [semantic versioning](https://github.com/semantic-release/semantic-release) +- Releases include notes on New Features, Bug Fixes, and any "Breaking Changes" + +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. + +Release notes are also a great opportunity to [praise participants](praise-participants.md)! As we know, [documentation is extremely important](project-setup/base-documentation.md) for new folks looking to get involved with your project. Praising outside teammates for contributions, including documentation and release notes, is a great way to foster community and grow your user base. + +## Known Instances + +* Comcast (multiple projects) +* GitHub (multiple projects) + +## Authors + +David Grizzanti + +## Status + +Structured diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md index 81c24c3d1..c7d699058 100644 --- a/patterns/2-structured/repository-activity-score.md +++ b/patterns/2-structured/repository-activity-score.md @@ -46,7 +46,7 @@ The repository activity score is a numeric value that represents the (GitHub) ac In addition, it considers activity parameters like last update and creation date of the repo to give young projects with a lot of traction a boost. Projects with contributing guidelines, active participation stats, and issues (public backlog) receive a higher ranking as well. -All of this can be fetched and calculated automatically using the result set of the [GitHub search API](https://docs.github.com/en/rest/search#search-repositories) and [GitHub statistics API](https://docs.github.com/en/rest/metrics/statistics). Other code versioning systems like BitBucket, Gitlab, Gerrit can be integrated as well if a similar API is available. +All of this can be fetched and calculated automatically using the result set of the [GitHub search API](https://docs.github.com/en/rest/search#search-repositories) and [GitHub statistics API](https://docs.github.com/en/rest/metrics/statistics). Other code versioning systems like Bitbucket, GitLab, Gerrit can be integrated as well if a similar API is available. The code below assumes the variable `repo` contains an entity fetched from the GitHub `search` API and the `participation` object contains an entity from the GitHub `stats/participation` API. @@ -114,7 +114,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances -* Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to InnerSourceCommons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). +* Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). ## Status @@ -124,7 +124,7 @@ The repository activity score is a simple calculation based on the GitHub API. I [Michael Graf (SAP)](mailto:mi.graf@sap.com) -## Acknowledgements +## Acknowledgments Thank you to the InnerSource Commons Community for lightning-fast advice, and a lot of helpful input to feed this pattern! Especially: diff --git a/patterns/2-structured/review-committee.md b/patterns/2-structured/review-committee.md index a0d72f03b..e1a47e48e 100644 --- a/patterns/2-structured/review-committee.md +++ b/patterns/2-structured/review-committee.md @@ -4,7 +4,7 @@ Review Committee ## Patlet -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. +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 familiarize themselves with the initiative and support it, as it affords them a certain level of oversight and control without fostering micromanagement. ## Problem diff --git a/patterns/2-structured/service-vs-library.md b/patterns/2-structured/service-vs-library.md index 8779615e4..51bde3c20 100644 --- a/patterns/2-structured/service-vs-library.md +++ b/patterns/2-structured/service-vs-library.md @@ -24,12 +24,12 @@ reluctant to join forces even if there is significant overlap in requirements. ## Context * Teams are working in a micro-services environment. -* They are organised in fully functional DevOps teams: Each team is responsible for their contributions end-to-end, including maintenance, on-call and customer support. +* They are organized in fully functional DevOps teams: Each team is responsible for their contributions end-to-end, including maintenance, on-call and customer support. * A team is tasked with providing a service to their downstream customers that is fairly similar to an existing service built by another team. ## Forces -* Organisational escalation paths may be different for each of the teams. +* Organizational escalation paths may be different for each of the teams. * Members of each team may be unwilling to answer on-call support for errors that do not affect their own downstream customers. * Severity levels for the same types of errors may be different across team boundaries due to different SLA definitions per team/customer relationship. * Teams may have different security or regulatory constraints governing their deployments. @@ -51,7 +51,7 @@ Deployment configurations can be included as separate projects in your InnerSour ## Resulting Context -Teams are willing to collaborate, benefitting from sharing the work of +Teams are willing to collaborate, benefiting from sharing the work of implementing the business logic. A service that originally was built specifically to work in one environment is @@ -61,10 +61,10 @@ Both teams get to know their respective escalation policy and deployment setup, potentially identifying improvements for their own setup. The likelihood that changes are needed and made in the shared source code -increases, leading to more frequent opportunities to refine, improve and optimise +increases, leading to more frequent opportunities to refine, improve and optimize the implementation. -Encourages incremental operational standardisation in release packaging, telemetry, health/readiness endpoints and so on as the teams realise they can more efficiently maintain this in the shared code if they agree on standard conventions. +Encourages incremental operational standardization in release packaging, telemetry, health/readiness endpoints and so on as the teams realize they can more efficiently maintain this in the shared code if they agree on standard conventions. ## See also @@ -73,7 +73,8 @@ Related to this pattern is the [30 Day Warranty](30-day-warranty.md) pattern tha ## Known Instances * Europace AG -* Flutter Entertainment: A [Flutter InnerSource application](https://innersource.flutter.com/sdlc/) has a shared code "service" repository with cross-team contribution and CI pipeline to build and publish a shared release artefact. Each adopting team has a "deployment config" repository defining their own deployment. This is driven by varying regulatory requirements, service and incident management practices and infrastructure skill sets in different areas of the business. +* Flutter Entertainment: A [Flutter InnerSource application](https://innersource.flutter.com/sdlc/) has a shared code "service" repository with cross-team contribution and CI pipeline to build and publish a shared release artifact. Each adopting team has a "deployment config" repository defining their own deployment. This is driven by varying regulatory requirements, service and incident management practices and infrastructure skill sets in different areas of the business. +* WellSky (see [Continuous InnerSource in Production - 5 Times](https://www.youtube.com/watch?v=loSTj4yIG9Q&pp=ygUkY29udGludW91cyBpbm5lcnNvdXJjZSBpbiBwcm9kdWN0aW9u)) ## Status @@ -84,7 +85,7 @@ Related to this pattern is the [30 Day Warranty](30-day-warranty.md) pattern tha * Isabel Drost-Fromm * Rob Tuley -## Acknowledgements +## Acknowledgments Thank you Tobias Gesellchen for review internal to Europace AG. diff --git a/patterns/2-structured/start-as-experiment.md b/patterns/2-structured/start-as-experiment.md index 12844e465..53326df2d 100644 --- a/patterns/2-structured/start-as-experiment.md +++ b/patterns/2-structured/start-as-experiment.md @@ -63,7 +63,7 @@ Finally, starting as an experiment makes it much easier to sidestep regulations - Georg Grütter (Robert Bosch GmbH) -## Acknowledgements +## Acknowledgments - Jason Zink (Robert Bosch GmbH) - Diogo Fregonese (Robert Bosch GmbH) diff --git a/patterns/2-structured/templates/rfc.md b/patterns/2-structured/templates/rfc.md index 34e858a99..d128e728d 100644 --- a/patterns/2-structured/templates/rfc.md +++ b/patterns/2-structured/templates/rfc.md @@ -1,6 +1,6 @@ # 000-Template -- Feature Name: (fill me in with a unique ident, `my_awesome_feature`) +- Feature Name: (fill me in with a unique identifier, `my_awesome_feature`) - Start Date: (fill me in with today's date, YYYY-MM-DD) - Nominated owners: (Representatives of technical ownership areas affected by the RFC. This will often be tech leads, but they may delegate. RFCs cannot be accepted until all nominated owners have signed off.) @@ -29,7 +29,7 @@ Explain the proposal as if it was already existing and you were teaching it to a - Introducing new named concepts. - Explaining the feature largely in terms of examples. - Explaining how engineers should think about the feature. It should explain the impact as concretely as possible. -- If applicable (eg code/architecture proposal), provide sample error messages, deprecation warnings, or migration guidance. +- If applicable (e.g. code/architecture proposal), provide sample error messages, deprecation warnings, or migration guidance. - If applicable, describe the differences between teaching this to existing engineers and new engineers. For implementation-oriented RFCs, this section should focus on how contributors should think about the change, and give examples of its concrete impact. For policy/process RFCs, this section should provide an example-driven introduction to the policy/process, and explain its impact in concrete terms. 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 484708276..f21de9753 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 @@ -60,7 +60,7 @@ Important elements of the solution are: ### 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 +- [Generalized BBC iPlayer & Sounds RFC template](templates/rfc.md), originally based on the [Rust][rust] template ## Resulting Context @@ -69,7 +69,7 @@ Implementing an RFC-like process has proven to be valuable, as it makes the cros Observable positive effects: - **democratization of the decision making process** for decisions that impact many teams (also offloading team leads from that burden) -- **a open asynchronous communication method** that works well across multiple teams and geos +- **a open asynchronous communication method** that works well across multiple teams and geographies - **empowers individuals and teams** to effect large scale change - **record of decisions made** for people to refer back to for context - **scales impact of experienced engineers** as they can contribute to solutions asynchronously and remotely, rather than needing to be present in a meeting diff --git a/patterns/2-structured/trusted-committer.md b/patterns/2-structured/trusted-committer.md index 3d04ecae4..085513c77 100644 --- a/patterns/2-structured/trusted-committer.md +++ b/patterns/2-structured/trusted-committer.md @@ -141,7 +141,7 @@ This has been tried and proven successful at: - [Fernando Freire] -## Acknowledgements +## Acknowledgments - [Russell Rutledge] - [Loren Sanz] diff --git a/translation/ja/patterns/extensions-for-sustainable-growth.md b/translation/ja/patterns/extensions-for-sustainable-growth.md new file mode 100644 index 000000000..23ff6c39f --- /dev/null +++ b/translation/ja/patterns/extensions-for-sustainable-growth.md @@ -0,0 +1,113 @@ +## Title + +持続可能な成長のためのエクステンション + +## Patlet + +インナーソースプロジェクトは多くのコントリビューションを受けており、メンテナンスが難しくなっています。メンテナは、プロジェクトのコア部分から離れた拡張機構を提供することで、最小のコストとメンテナンスオーバーヘッドでプロジェクトの能力をスケールアップすることを可能にします。 + +## 問題 + +成熟したインナーソースリポジトリへのコントリビューションが急速に増えると、コードレビューやメンテナンスの負担が増大します。これにより、大量のコードレビューのバックログが生じたり、新しい機能のコントリビューションが早期に拒否されたりする結果となります。 + +ホストチームは、新しい機能のリリースをより早く行い、イノベーションと実験を奨励しつつ、リポジトリを適切にメンテナンスするためにはどのようにすればよいのでしょうか？ + +## ストーリー + +特定のドメインスペース内での最高のイノベーションを一つの共通スタックに集め、共通のインフラストラクチャの再利用を可能にし、標準的なユーザーエクスペリエンスを提供することを目指す戦略的なプロジェクトが存在します。インナーソースを通じて、組織内の各チームは、そのドメインスペース内で働きながら、共通のコードベースにイノベーションをコントリビューションする機会を得ます。 + +しかし、複数の開発者からの並行したコントリビューションが多くなると、コードベースのメンテナンスが難しくなります。 +それは、プロジェクトのメンテナはコードの品質基準に対するオーナーシップを引き受けることになり、さまざまな形式のコミュニケーションを通じてコミュニティを支えるという大きな負担がかかるからです。 + +プロジェクトのメンテナは以下のようなリスクに直面しています: + +- コントリビューターからのプルリクエストのバックログが絶えず存在する +- 職業の不満: メンテナの時間の大部分がコミュニティサポートの支援に使われてしまい、新しいことに挑戦する時間がない +- 成果感の欠如: 提供されたすべての機能が適切なユーザー需要を満たすわけではなく、それによって結果的に採用されるとは限らない +- リリースに時間がかかる: コードベースに多くの機能があると、テストに時間がかかる +- メンテナンス活動の増加: 新しい機能が追加されると、バグが増える + +可能性のあるユーザーがその機能を自分のユースケースに適用する機会を得る前に、新しい機能のコントリビューションが成熟するまでに多くの時間が費やされています。もし新しい機能がユースケースを満たさなければ、求められていたコード品質基準を達成するために費やした全ての時間が無駄になります。 + +## 状況 + +- 戦略的なインナーソースコードベースが、多数の従業員からの新機能のコントリビューションで急速にスケールアップしています。 +- レビュアーとコントリビューションの比率により、プルリクエストのバックログが増加しています。これにより、新機能のリリースがコミュニティに対して遅くなっています。 +- コードベースの品質が劣化し、ユーザーエクスペリエンスが悪化しています。 +- コードベースのメンテナが負荷を感じ、コントリビューションの増加とコミュニティサポートの増加に対応できなくなっています。 +- 提供された機能の一部はユーザーに採用されず、完全に不活動になる可能性があります。しかし、それらが使用されていないにもかかわらず、これらの機能は依然としてメンテナンスのオーバーヘッドを増やしています。 +- 組織は、新しい機能のコントリビューションを品質基準を保持するために厳しく対応している一方で、コミュニティがアイデアを探求する前に大量の投資を行っています。 +- 次の2つのシナリオのどちらかでパターンが適用されます: + - メンテナがプロジェクトの範囲を絞り込むために、自身で新しい機能のアイデアを拒否することにより、コミュニティのイノベーションを阻害し、さらなる拡大を制限しています。 + - バックログを減らすために、新しい機能が十分なドキュメンテーション、ハードニング、テストなしにリリースされ、ユーザー体験が悪化します。これにより、コードベースのサイズが大きくなり、依存関係が大きくなり、メンテナンスが難しくなります。 + +## 組織に働く力学 + +- メンテナとプロダクトオーナーは、拡張、イノベーション、実験を促進しつつ、コントリビューションに対して過度に制限を設けずに、良好なコードと品質基準を保持したいと考えています。 +- 特性を製品基準に適合させ、徹底的にテストするために多くの時間が費やされますが、製品オーナーは新しいイノベーションを機能が成熟する前に製品が探求できるように、新しいイノベーションのリリースを早めたいかもしれません。 +- メンテナは、プライマリリポジトリにより多くの依存関係を追加せずに、コミュニティが製品の機能と他のユースケースを組み合わせたイノベーションを共有することを奨励したいと考えています。 + +## ソリューション + +高規模なインナーソースコードベースへの[拡張/プラグイン(英語)](https://en.wikipedia.org/wiki/Extensibility)を許可することで、リポジトリのメンテナに対するメンテナンスの負担を軽減し、新機能のリリースを探求する製品のリリースを早めることができます。これにより、機能のメンテナンスを拡張所有者に移し、プライマリリポジトリがより広範に採用され、より戦略的にサポートされる機能を支援することが可能になります。 + +拡張機能は、最終的にプロジェクトのコアに移動する可能性のある新たな機能のフィルターとして機能します。また、拡張機能はインキュベーションとコミュニティのハードニング環境としても機能し、そのハードニングが高価なレビュープロセスではなく、自然に行われるようにします。 + +拡張モデルを成功させるためには、いくつかのアーキテクチャ上の考慮事項が必要です: + +1. **作成が簡単:** コミュニティの参加を得るためには、拡張機能を簡単に作成できる必要があります。 + - 拡張機能がスタートポイントとして使用するべきリポジトリテンプレートを作成します。これにより、拡張機能は新しいリポジトリに新機能を追加することができ、コアプロジェクトとは別になります。テンプレートはプライマリリポジトリと同じモジュール構造を提供し、拡張機能のパッケージ化とリリースのフレームワークを含むべきです。 + - プライマリリポジトリが変更されると、テンプレートが適切に保守されていることを確認します。プライマリリポジトリのメンテナがテンプレートを更新し、メインプロジェクトとの互換性を保証します。良いバージョニング規則を守ること、例えば、[semver](https://semver.org/)の使用がこれを容易にします。 + - さらに、新しいバージョンがリリースされると、プライマリリポジトリのメンテナが古いバージョンのテンプレートに基づく拡張機能の更新方法についてのガイドラインを提供することを推奨します。 + - テンプレートから開発された拡張機能の例を追加します。これにより、プロジェクトの開発者は、どのようにして良いパターンの拡張機能を書くべきかを理解することができます。 + - レビューをバイパスして拡張機能を作成する寄稿者の要件を緩和し、リリースや実験を早めることを許可します。 +2. **疎結合:** 機能を含むモジュラーなコンポーネントを持つことで、拡張機能への変更がメインコードベースや他の拡張機能の品質に影響を与えない疎結合を可能にすることができます。 +3. **依存性管理:** 各拡張は、それが構築されるプライマリリポジトリのバージョン範囲をピン留めするように注意する必要があります（他の依存関係と同じように）。また、それがプライマリリポジトリの依存関係をシャドーする他の依存関係の使用についても注意深くなければなりません。選択した依存関係のバージョンがプライマリリポジトリの選択したバージョンと互換性があるようにします。プライマリリポジトリとの任意の競合は、拡張のテストフレームワークで検出できます。 +4. **テスト戦略:** 拡張機能を個別に、または組み合わせてテストする方法は？ + - **拡張機能を個別にテストする:** 拡張機能のテンプレートは、拡張機能の開発者が追加した機能をテストするためのテストフレームワークを提供します。これには、ユニットテスト、ランタイムパフォーマンステスト、品質テストのフレームワークが含まれることがあります。 + - **拡張機能をプライマリリポジトリと組み合わせてテストする:** 拡張機能の開発者は、プライマリリポジトリの特定のバージョンに対して自分の拡張機能をテストするための良好なパターンの方法を持つべきで、これにはプライマリリポジトリのメンテナの関与は必要ありません。 + - **拡張機能を他の拡張機能と組み合わせてテストする:** このシナリオのためにテストフレームワークを提供することは、特に、ユーザによってまだ調査中であり、すべての拡張機能を組み合わせて使用する可能性が低い多数の拡張機能がある場合、過剰になる可能性があります。もしユーザが拡張機能を組み合わせて使っているときにコンフリクトに遭遇した場合 (十分な疎結合であればありえないはずです)、ユーザはそれぞれの拡張機能の所有者に問題を提起することができます。拡張機能がライフサイクルの後半に達し、プライマリリポジトリにマージされるようになると、ライブラリの残りの部分と組み合わせてテストされるようになり、依存関係の衝突はその時点で解決されなければならなくなります。 +5. **発見性と利便性:** + - ユーザーが作成し、製品の使用に共有したいと思っている拡張機能を表示する公開ページで、拡張機能を容易に発見できるようにします。 + - ユーザーが元のプロジェクトと一緒に拡張機能を利用できるように、プライマリプロジェクトに拡張機能の登録を許可します。これにより、同じユーザーエクスペリエンスが維持されます。 +6. **拡張機能のライフサイクルと保守性:** 拡張機能の作成からプライマリコードベースへの移植までのライフサイクルを確立し、明確な所有権ガイドラインを作成します。 + - 拡張機能の作成者は、拡張機能のメンテナンスを続け、サポートを提供し、欠陥を修正します。保守されていない拡張機能は、公開ページからリストから削除されます。 + - 内部製品による拡張機能の採用と機能への需要など、プライマリリポジトリへの移植が可能になる基準を作成します。 + - 拡張機能のプライマリリポジトリへの移植プロセスは、ライブラリメンテナによって設定されたより厳格なコードレビューガイドラインに従います。 + +![ソフトウェアアーキテクチャと拡張機能](../../../assets/img/extensions-for-sustainable-growth/extensions-for-sustainable-growth.png) + +これらの原則に従うことで、以下が確保されます: + +- 開発者は、大量の[ボイラーテンプレート(定型)](https://en.wikipedia.org/wiki/Boilerplate_code)コードを書くことなく、プロジェクトのエコシステムに新しい機能を追加することができます。 +- 拡張機能は、プライマリプロジェクトの全てのユーザーによって反復可能な方法で発見できます。コードがまだメインリポジトリに存在していないとしても、それが価値がないわけではありません。 +- メンテナの負担は、拡張機能がプライマリプロジェクトで重要なギャップを埋めていることを示すまで軽減されます。 +- コアプロジェクトの共通コード（例えば、ベースクラスやユーティリティ関数）は、プロジェクトの領域を拡張する新しい開発の出発点となります。これにより、革新的な作業を後から移植する必要がなくなり、プロジェクトにとって新しい機能を開発する全体的な負担を軽減します。 +- 開発者は、コードベースのためのコミュニティのメンテナンスとコミュニティ構築にコントリビューションし、関与し続ける可能性が高くなります。これは全体のプロジェクトエコシステムの健康にも良い影響を与えます。 + +## 結果の状況 + +- プロジェクトは、新しい機能の追加により拡大することができ、プライマリプロジェクトリポジトリにメンテナンスのオーバーヘッドを追加することなく、拡大することができます。 +- コミュニティが探求する新機能のリリースが早まり、革新と実験を奨励します。 +- 機能がその有用性を証明するまで、高額なコードレビューと機能強化プロセスが削減されます。これにより、組織に対するコスト節約の利益が得られます。 +- 一つの問題が導入される可能性があります - 拡張機能がフルライフサイクルを完了できない場合、何が起こりますか？ + - 拡張機能が一定期間採用されず、それをサポートするコミュニティを形成できなかった場合、そのメンテナンスを続けるかどうかは拡張機能のオーナー次第です。もし拡張機能がメンテナンスされなくなった場合、それは非公開になります。 + - 拡張機能の開発者がそれ以上のプロジェクトを維持できなくなり、コミュニティ内の他の開発者がそれを引き続きサポートしたい場合、彼らはその拡張機能の維持を進めていくことができます。 + +## 事例 + +* **IBM社**は、[インナーソース AIライブラリ](https://youtu.be/Lz-tIc2cyRM)を拡大するためにこの解決策を採用しています。拡張機能を使用することで、開発者はAIライブラリに更に多くのアルゴリズムを追加し、彼らの革新を企業内のコミュニティと共有することができます。コアライブラリには、採用されて検証された戦略的なアルゴリズムのみが含まれており、これにより我々はコントリビューションをスケールするにつれてそれらをより簡単に維持することができます。 + +## エイリアス + +大規模にコントリビューションを管理するための拡張 + +## ステータス + +* Structured + +## 著者 + +- Sukriti Sharma, IBM +- Alexander Brooks, IBM +- Gabe Goodhart, IBM diff --git a/translation/ja/patterns/innersource-portal.md b/translation/ja/patterns/innersource-portal.md index 3d64de4af..df90eaceb 100644 --- a/translation/ja/patterns/innersource-portal.md +++ b/translation/ja/patterns/innersource-portal.md @@ -75,7 +75,7 @@ * **アメリカン航空**は、[インターナルインナーソースマーケットプレイス](https://tech.aa.com/2020-10-30-innersource/)を介してInnerSourceプロジェクトを推進しています。SAPと同様に、プロジェクトはGitHubのトピックとして `innersource` を追加することで自己登録されます。プロジェクトは、言語、トピック、オープンイシューの数などで検索やフィルタリングが可能です。 -* **Banco Santander**社は、インナーソースをサポートして増やすために、[Santander ONE Europe InnerSource Community](https://innersourceportal.santander.com/)という公開ポータルを作成しました。このポータルには、プロジェクトのカタログに加え、ドキュメント、仕事の進め方、ニュース、イベントなどの関連コンテンツが含まれています。 +* **Banco Santander**社は、インナーソースをサポートして増やすために、Santander ONE Europe InnerSource Communityという公開ポータルを作成しました。このポータルには、プロジェクトのカタログに加え、ドキュメント、仕事の進め方、ニュース、イベントなどの関連コンテンツが含まれています。 ![Santander InnerSource Portal](../../../assets/img/santander_portal.png "Banco Santander InnerSource Portal")