From afd7d1c1c28cda719a1a42de5172dc37ca8470bf Mon Sep 17 00:00:00 2001 From: Sebastian Spier Date: Sat, 2 Dec 2023 10:52:51 +0100 Subject: [PATCH] Move files from project-setup to standard folders (#633) * Move files from project-setup to standard folders * Fix all links from patterns to project-setup folder * Fix all links from translations to project-setup folder * Remove instances of project/setup in book and scripts * Point from old project-setup folder to the new folder for these files * Regenerate en toc.me locally. Not sure why the GHA did not do this. --- .github/workflows/lint-patterns.yml | 5 ++--- README.md | 6 +++--- assets/img/standard-base-documentation/README.md | 2 +- .../base_docs_drawing.png | Bin .../base_docs_drawing.svg | 0 book/en/toc.md | 12 ++++++------ book/en/toc_template.md | 6 +++--- book/scripts/generate_toc.rb | 2 +- meta/boardreports/2023-11.md | 2 +- meta/scripts/find_upgradeable_patterns.rb | 2 +- patterns/1-initial/explicit-shared-ownership.md | 2 +- patterns/1-initial/governance-levels.md | 2 +- patterns/1-initial/innersource-guidance-group.md | 2 +- patterns/2-structured/30-day-warranty.md | 2 +- .../{project-setup => }/base-documentation.md | 8 ++++---- .../{project-setup => }/communication-tooling.md | 4 ++-- patterns/2-structured/group-support.md | 4 ++-- .../{project-setup => }/issue-tracker.md | 0 patterns/2-structured/project-setup/README.md | 3 +++ patterns/2-structured/release-process.md | 2 +- patterns/2-structured/repository-activity-score.md | 2 +- .../templates/COMMUNICATION-template.md | 0 .../templates/CONTRIBUTING-template.md | 0 .../templates/README-template.md | 0 translation/ja/patterns/base-documentation.md | 2 +- 25 files changed, 36 insertions(+), 34 deletions(-) rename {patterns/2-structured/project-setup/assets => assets/img/standard-base-documentation}/base_docs_drawing.png (100%) rename {patterns/2-structured/project-setup/assets => assets/img/standard-base-documentation}/base_docs_drawing.svg (100%) rename patterns/2-structured/{project-setup => }/base-documentation.md (95%) rename patterns/2-structured/{project-setup => }/communication-tooling.md (93%) rename patterns/2-structured/{project-setup => }/issue-tracker.md (100%) create mode 100644 patterns/2-structured/project-setup/README.md rename patterns/2-structured/{project-setup => }/templates/COMMUNICATION-template.md (100%) rename patterns/2-structured/{project-setup => }/templates/CONTRIBUTING-template.md (100%) rename patterns/2-structured/{project-setup => }/templates/README-template.md (100%) diff --git a/.github/workflows/lint-patterns.yml b/.github/workflows/lint-patterns.yml index 408619ea7..14d4f2b33 100644 --- a/.github/workflows/lint-patterns.yml +++ b/.github/workflows/lint-patterns.yml @@ -1,6 +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 +# markdownlint -r config/lint/pattern-template.js -c config/lint/pattern-template.yml patterns/2-structured/*.md patterns/3-validated/*.md name: Pattern Syntax Validation on: @@ -12,7 +12,6 @@ on: - ".github/workflows/lint-patterns.yml" - ".github/lint-pattern-syntax/*" - "patterns/2-structured/*.md" - - "patterns/2-structured/project-setup/*.md" - "patterns/3-validated/*.md" jobs: @@ -27,4 +26,4 @@ jobs: with: 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' + args: 'patterns/2-structured/*.md patterns/3-validated/*.md' diff --git a/README.md b/README.md index bc97e53cf..38fc45d43 100644 --- a/README.md +++ b/README.md @@ -47,9 +47,9 @@ Our mission * [Review Committee](patterns/2-structured/review-committee.md) - *The InnerSource working model is a radical departure from more traditional approaches, for developers and managers alike. By establishing a review committee as an interface between the InnerSource initiative and all senior managers of business units participating in it, the latter are more likely to familiarise themselves with the initiative and support it, as it affords them a certain level of oversight and control without fostering micromanagement.* * [Service vs. Library](patterns/2-structured/service-vs-library.md) - *Teams in a DevOps environment may be reluctant to work across team boundaries on common code bases due to ambiguity over who will be responsible for responding to service downtime. The solution is to realize that often it's possible to either deploy the same service in independent environments with separate escalation chains in the event of service downtime or factor a lot of shared code out into one library and collaborate on that.* * [Trusted Committer](patterns/2-structured/trusted-committer.md) - *Many InnerSource projects will find themselves in a situation where they consistently receive feedback, features, and bug-fixes from contributors. In these situations project maintainers seek ways to recognize and reward the work of the contributor above and beyond single contributions.* -* [Standard Base Documentation](patterns/2-structured/project-setup/base-documentation.md) - *New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own.* -* [Issue Tracker Use Cases](patterns/2-structured/project-setup/issue-tracker.md) - *The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design.* -* [Communication Tooling](patterns/2-structured/project-setup/communication-tooling.md) - *The users of an InnerSource project have trouble getting help and getting in touch with the host team. By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users.* +* [Standard Base Documentation](patterns/2-structured/base-documentation.md) - *New contributors to an InnerSource project have a hard time figuring out who maintains the project, what to work on, and how to contribute. Providing documentation in standard files like README.md/CONTRIBUTING.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own.* +* [Issue Tracker Use Cases](patterns/2-structured/issue-tracker.md) - *The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design.* +* [Communication Tooling](patterns/2-structured/communication-tooling.md) - *The users of an InnerSource project have trouble getting help and getting in touch with the host team. By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users.* * [Cross-Team Project Valuation](patterns/2-structured/crossteam-project-valuation.md) - *It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it.* * [Transparent Cross-Team Decision Making using RFCs](patterns/2-structured/transparent-cross-team-decision-making-using-rfcs.md) - *InnerSource projects that want to achieve high participation rates and make the best possible decisions for everybody involved need to find ways to create participatory systems throughout the full software lifecycle. Publishing internal Requests for Comments (RFCs) documents allows for discussions early on in the design process, and increases the chances to build solutions with a high degree of commitment from all involved parties.* * [Start as an Experiment](patterns/2-structured/start-as-experiment.md) - *Start your InnerSource initiative as a time limited experiment to make it easier for managers unfamiliar with InnerSource to endorse and support the initiative.* diff --git a/assets/img/standard-base-documentation/README.md b/assets/img/standard-base-documentation/README.md index 22160c45a..7eacaf14d 100644 --- a/assets/img/standard-base-documentation/README.md +++ b/assets/img/standard-base-documentation/README.md @@ -1,6 +1,6 @@ # Credits -The current illustration is a digital remake of this [original visual](/patterns/2-structured/project-setup/assets/base_docs_drawing.png). +The current illustration is a digital remake of this [original visual](./base_docs_drawing.png). If you want to edit this illustration, please request access to this [source document](https://docs.google.com/presentation/d/11JOByEO9QXlRLXX5BIv9rjUzPzCKErZzknD1OLcprQQ/edit?usp=sharing). The humans in the illustration are [bro](https://storyset.com/illustration/coding/bro) and [pana](https://storyset.com/illustration/high-five/pana) from Storyset. diff --git a/patterns/2-structured/project-setup/assets/base_docs_drawing.png b/assets/img/standard-base-documentation/base_docs_drawing.png similarity index 100% rename from patterns/2-structured/project-setup/assets/base_docs_drawing.png rename to assets/img/standard-base-documentation/base_docs_drawing.png diff --git a/patterns/2-structured/project-setup/assets/base_docs_drawing.svg b/assets/img/standard-base-documentation/base_docs_drawing.svg similarity index 100% rename from patterns/2-structured/project-setup/assets/base_docs_drawing.svg rename to assets/img/standard-base-documentation/base_docs_drawing.svg diff --git a/book/en/toc.md b/book/en/toc.md index 68a11386b..484898abb 100644 --- a/book/en/toc.md +++ b/book/en/toc.md @@ -21,7 +21,7 @@ Instead edit toc_template.md * [30 Day Warranty](../../patterns/2-structured/30-day-warranty.md) - When accepting contributions from outside of your own team, there is a natural aversion to taking responsibility for code not written by the team itself. Through the 30 Day Warranty the contributing team consents to provide bug fixes to the receiving team, which will increase the level of trust between both teams and makes it more likely that contributions get accepted. * [Common Requirements](../../patterns/2-structured/common-requirements.md) - Common code in a shared repository isn't meeting the needs of all the project-teams that want to use it; this is solved through requirements alignment and refactoring. -* [Communication Tooling](../../patterns/2-structured/project-setup/communication-tooling.md) - The users of an InnerSource project have trouble getting help and getting in touch with the host team. By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. +* [Communication Tooling](../../patterns/2-structured/communication-tooling.md) - The users of an InnerSource project have trouble getting help and getting in touch with the host team. By consistently using asynchronous communication tooling, the project makes discussions visible, archived and searchable, leading to an improved level of support for users. * [Contracted Contributor](../../patterns/2-structured/contracted-contributor.md) - Associates wanting to contribute to InnerSource are discouraged from doing so by their line management. Relief is provided by formal contracts and agreements. * [Core Team](../../patterns/2-structured/core-team.md) - Even when an InnerSource project is widely needed, contributions and usage may be hindered because the project is difficult to work with. Establish a core team that is dedicated to take care of the project's fundamental items. Their work enables contributors to add and use the features that provide value to their scenarios. * [Cross-Team Project Valuation](../../patterns/2-structured/crossteam-project-valuation.md) - It's hard to sell the value of cross-team InnerSource projects that don't provide a direct impact on company revenue. Here's a data-driven way to represent your project that both articulates its value and amplifies it. @@ -32,13 +32,13 @@ Instead edit toc_template.md * [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. * [InnerSource License](../../patterns/2-structured/innersource-license.md) - Two legal entities that belong to the same organization want to share software source code with each other but they are concerned about the implications in terms of legal liabilities or cross-company accounting. * [InnerSource Portal](../../patterns/2-structured/innersource-portal.md) - Potential contributors cannot easily discover InnerSource projects that they are interested in. By creating an intranet website that indexes all available InnerSource project information you enable contributors to learn about projects that might interest them and InnerSource project owners to attract an outside audience. -* [Issue Tracker Use Cases](../../patterns/2-structured/project-setup/issue-tracker.md) - The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design. +* [Issue Tracker Use Cases](../../patterns/2-structured/issue-tracker.md) - The InnerSource host team fails to make not only plans and progress but also context for changes transparent. This is solved by increasing the use cases for the project issue tracker to also serve brainstorming, implementation discussion, and feature design. * [Maturity Model](../../patterns/2-structured/maturity-model.md) - Teams have started adopting InnerSource. The practice is spreading to multiple departments. However, the understanding of what constitutes an InnerSource project varies. The solution is to provide a maturity model to allow for teams to go through a self check and discover patterns and practices that they are not yet aware of. * [Praise Participants](../../patterns/2-structured/praise-participants.md) - After an inner source contribution, it's important to thank the contributor for their time and effort. This pattern gives guidance that not only effectively acknowledges the contribution but also engenders further engagement from the contributor and others. * [Repository Activity Score](../../patterns/2-structured/repository-activity-score.md) - Potential contributors want to find active InnerSource projects in need of their help. By calculating a repository activity score for each project, a ranked list of projects can be created (e.g. on the InnerSource Portal), so that potential contributors can more easily determine which project they want to contribute to. * [Review Committee](../../patterns/2-structured/review-committee.md) - The InnerSource working model is a radical departure from more traditional approaches, for developers and managers alike. By establishing a review committee as an interface between the InnerSource initiative and all senior managers of business units participating in it, the latter are more likely to 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/COMMUNICATION.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own. +* [Standard Base Documentation](../../patterns/2-structured/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/COMMUNICATION.md enables a self service process for new contributors, so that they can find the answers to the most common questions on their own. * [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. @@ -48,9 +48,9 @@ Instead edit toc_template.md * [Pattern Template](../../meta/pattern-template.md) * Extras - * [README Template](../../patterns/2-structured/project-setup/templates/README-template.md) - * [CONTRIBUTING Template](../../patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md) - * [COMMUNICATION Template](../../patterns/2-structured/project-setup/templates/COMMUNICATION-template.md) + * [README Template](../../patterns/2-structured/templates/README-template.md) + * [CONTRIBUTING Template](../../patterns/2-structured/templates/CONTRIBUTING-template.md) + * [COMMUNICATION Template](../../patterns/2-structured/templates/COMMUNICATION-template.md) * [RFC Template](../../patterns/2-structured/templates/rfc.md) ## Resources diff --git a/book/en/toc_template.md b/book/en/toc_template.md index cb7b3b956..85aea6452 100644 --- a/book/en/toc_template.md +++ b/book/en/toc_template.md @@ -25,9 +25,9 @@ Instead edit toc_template.md * [Pattern Template](../../meta/pattern-template.md) * Extras - * [README Template](../../patterns/2-structured/project-setup/templates/README-template.md) - * [CONTRIBUTING Template](../../patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md) - * [COMMUNICATION Template](../../patterns/2-structured/project-setup/templates/COMMUNICATION-template.md) + * [README Template](../../patterns/2-structured/templates/README-template.md) + * [CONTRIBUTING Template](../../patterns/2-structured/templates/CONTRIBUTING-template.md) + * [COMMUNICATION Template](../../patterns/2-structured/templates/COMMUNICATION-template.md) * [RFC Template](../../patterns/2-structured/templates/rfc.md) ## Resources diff --git a/book/scripts/generate_toc.rb b/book/scripts/generate_toc.rb index 07a51f590..3a42b7088 100644 --- a/book/scripts/generate_toc.rb +++ b/book/scripts/generate_toc.rb @@ -77,7 +77,7 @@ def generate_patterns_overview(patterns) if (BOOK_LANGUAGE == "en") TOC_TEMPLATE_FILE = "../en/toc_template.md" TOC_FILE = "../en/toc.md" - PATTERNS = Dir["../../patterns/2-structured/*.md","../../patterns/2-structured/project-setup/*.md", "../../patterns/3-validated/*.md"] + PATTERNS = Dir["../../patterns/2-structured/*.md", "../../patterns/3-validated/*.md"] else TOC_TEMPLATE_FILE = "../#{BOOK_LANGUAGE}/toc_template.md" TOC_FILE = "../#{BOOK_LANGUAGE}/toc.md" diff --git a/meta/boardreports/2023-11.md b/meta/boardreports/2023-11.md index df8c1a372..7a4bc88d4 100644 --- a/meta/boardreports/2023-11.md +++ b/meta/boardreports/2023-11.md @@ -36,7 +36,7 @@ Changes are contributed via the [InnerSourcePatterns][] repository: * GitHub to [Standard Release Process](https://patterns.innersourcecommons.org/p/release-process) * experimenting with various tools to understand the contribution patterns of our community better. e.g. see [these stats](https://github.com/InnerSourceCommons/InnerSourcePatterns/issues/625) - shout outs to **@zkoppert** not only for building these tools but also for helping us to integrate them into our repo * added a **welcome bot** to our repo, that greats new contributors and points them to helpful info about our contribution process - see [this example](https://github.com/InnerSourceCommons/InnerSourcePatterns/pull/573) -* by using gitbook's "monorepo approach", we are now able to deploying multiple translations in parallel via gitbook a lot easier +* by using gitbook's "monorepo approach", we are now able to deploying multiple translations in parallel via gitbook a lot easier * added a new `COMMUNICATION-template.md` to streamline the communication to the **Standard Base Documentation** pattern. - thank you **@kschueths** ## Things to come diff --git a/meta/scripts/find_upgradeable_patterns.rb b/meta/scripts/find_upgradeable_patterns.rb index b80bde4fb..2ac5710a6 100644 --- a/meta/scripts/find_upgradeable_patterns.rb +++ b/meta/scripts/find_upgradeable_patterns.rb @@ -76,7 +76,7 @@ def collect_section_nodes(file, section_title) 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 = Dir["../../patterns/2-structured/*.md"] l2_patterns.each do |file| known_instances_count = count_known_instances(file) diff --git a/patterns/1-initial/explicit-shared-ownership.md b/patterns/1-initial/explicit-shared-ownership.md index aadcf36c9..87104cb76 100644 --- a/patterns/1-initial/explicit-shared-ownership.md +++ b/patterns/1-initial/explicit-shared-ownership.md @@ -41,7 +41,7 @@ A volunteer creates an issue in the component's repository highlighting the appa There is an initial team of [Trusted Committers](../2-structured/trusted-committer.md) committed to the component. -Expectations related to collaboration are transparent for everyone involved going forward e.g. by creating [base documentation in CONTRIBUTING.md](../2-structured/project-setup/base-documentation.md). +Expectations related to collaboration are transparent for everyone involved going forward e.g. by creating [base documentation in CONTRIBUTING.md](../2-structured/base-documentation.md). The entire decision process backing the result is transparent and can be influenced by those affected, leading to higher buy-in for the final result. Also the argument leading to the final decisions are accessible for those new to the project. diff --git a/patterns/1-initial/governance-levels.md b/patterns/1-initial/governance-levels.md index 996ce276b..2b64bee67 100644 --- a/patterns/1-initial/governance-levels.md +++ b/patterns/1-initial/governance-levels.md @@ -69,7 +69,7 @@ Examples of common InnerSource operating models (1) are: Examples of promoting the model names (3) are: -- Using the names within project documentation and contributing guides (see also [Standard Base Documentation](../2-structured/project-setup/base-documentation.md)). +- Using the names within project documentation and contributing guides (see also [Standard Base Documentation](../2-structured/base-documentation.md)). - Labelling projects with the names in an [InnerSource Portal](../2-structured/innersource-portal.md). - Presenting the names as a menu of adoption options for new InnerSource projects. - Including the names and models in any internal InnerSource training or promotion. diff --git a/patterns/1-initial/innersource-guidance-group.md b/patterns/1-initial/innersource-guidance-group.md index 9683d3320..ade83ae55 100644 --- a/patterns/1-initial/innersource-guidance-group.md +++ b/patterns/1-initial/innersource-guidance-group.md @@ -33,7 +33,7 @@ Recognize that Trusted Committers are both **situational leaders** and **subject - The “committee” is scheduled periodically as necessary by the Trusted Committers – twice a week, once a month, quarterly, etc. - The goal is to establish general direction, or a highway, while leaving freedom for individual teams to adapt to local needs, or side streets -- Trusted Committers establish organization guidelines that become templates for [Contribution Agreements](../2-structured/project-setup/base-documentation.md) +- Trusted Committers establish organization guidelines that become templates for [Contribution Agreements](../2-structured/base-documentation.md) - Trusted Committers collaborate on and refine guidelines asynchronously via passive documentation and the establishment of organizational patterns. - This guideline definition project itself can be run as an InnerSource project, accepting contributions from anywhere in the organization. - By running this as a collaborative documentation project, it can role-model and verify the behaviors that they want to promote for other InnerSource projects as well. diff --git a/patterns/2-structured/30-day-warranty.md b/patterns/2-structured/30-day-warranty.md index 7c2ab75c3..ce93a1b13 100644 --- a/patterns/2-structured/30-day-warranty.md +++ b/patterns/2-structured/30-day-warranty.md @@ -34,7 +34,7 @@ Address the fears of both the receiving and the contributing teams by establishi Note that the warranty period could be 45, 60, or 100 days too. The duration may vary based upon the constraints of the project, the software life cycle of the project, commitments to customers, and other factors. -In addition it helps to provide clear [contribution guidelines](./project-setup/base-documentation.md), spelling out the expectations of the receiving team and the contributing team. +In addition it helps to provide clear [contribution guidelines](./base-documentation.md), spelling out the expectations of the receiving team and the contributing team. ![30 Day Warranty](../../assets/img/thirtydaywarranty.jpg) diff --git a/patterns/2-structured/project-setup/base-documentation.md b/patterns/2-structured/base-documentation.md similarity index 95% rename from patterns/2-structured/project-setup/base-documentation.md rename to patterns/2-structured/base-documentation.md index 3c4bb411b..bd20b821b 100644 --- a/patterns/2-structured/project-setup/base-documentation.md +++ b/patterns/2-structured/base-documentation.md @@ -58,10 +58,10 @@ contain: * Documentation needed for making modifications to the project - or a link to that. * Documentation on how to contribute to the project - or a link to that. * A "Getting involved" section that explains which public, archived, linkable communication channels the project uses. This should include a link to the project issue tracker, but also to any further discussion media used. -* A "Who we are" section explaining who the [Trusted Committers](../trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. +* A "Who we are" section explaining who the [Trusted Committers](trusted-committer.md) behind the project are - with an explanation that instead of contacting these people privately the public communication channels above should be used for communication. * An explanation of what the criteria are for the project to turn contributors into Trusted Committers - if that path exists. -![README.md](../../../assets/img/standard-base-documentation/README-for-users.png) +![README.md](../../assets/img/standard-base-documentation/README-for-users.png) ### CONTRIBUTING.md @@ -79,7 +79,7 @@ topics: * How to submit your modifications back to the project. * Some information on which turnaround time to expect for modifications made. -![CONTRIBUTING.md](../../../assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png) +![CONTRIBUTING.md](../../assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png) ### COMMUNICATION.md @@ -123,7 +123,7 @@ started right away: [README-template.md](templates/README-template.md), ## Resulting Context * The time for contributors to get up to speed is significantly reduced. -* Time spent on answering initial questions for [Trusted Committers](../trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. +* Time spent on answering initial questions for [Trusted Committers](trusted-committer.md) is significantly reduced, leaving them more time to work on other tasks. * Escalations due to misunderstandings and misalignment are significantly reduced. ## Known Instances diff --git a/patterns/2-structured/project-setup/communication-tooling.md b/patterns/2-structured/communication-tooling.md similarity index 93% rename from patterns/2-structured/project-setup/communication-tooling.md rename to patterns/2-structured/communication-tooling.md index 67ad6b844..08b1a33d3 100644 --- a/patterns/2-structured/project-setup/communication-tooling.md +++ b/patterns/2-structured/communication-tooling.md @@ -39,7 +39,7 @@ A project should set up the following communication tooling: 1. **a dedicated issue tracker** where structured communication, decision-making and progress tracking can happen transparently for all host team members but also for downstream users and contributors to follow. For further applications of the issue tracker see [Issue Tracker Use Cases](./issue-tracker.md). 2. **public discussion channel(s)** that come with less rigid a structure. Typically, this will be mailing lists, online forums, Q&A systems or even archived chat channels. Usually it is enough to start with just one channel for the project. If traffic increases too much it is helpful to split discussions about project usage from discussions about project development. -3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](../trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. +3. **a private channel** where communication about sensitive topics can happen between [Trusted Committers](./trusted-committer.md) - e.g. adding further Trusted Committers to the host team. This channel should be used with great care such that communication defaults to open and is kept private only under very rare circumstances. While communication can happen outside of those written channels, as much information as possible should be brought back to the asynchronous channels. @@ -47,7 +47,7 @@ All communication channels should be documented in the project `README.md`. For The host team members need to make an effort to direct questions that they receive personally (e.g. via email or private chat messages) back to official communication channels. -![Recommended Communication Tooling for an InnerSource Project](../../../assets/img/communication-tooling/communication-tooling.png) +![Recommended Communication Tooling for an InnerSource Project](../../assets/img/communication-tooling/communication-tooling.png) ## Resulting Context diff --git a/patterns/2-structured/group-support.md b/patterns/2-structured/group-support.md index 12396aaeb..9bf49202e 100644 --- a/patterns/2-structured/group-support.md +++ b/patterns/2-structured/group-support.md @@ -80,7 +80,7 @@ Structured [Russell R. Rutledge][] [Russell R. Rutledge]: https://github.com/rrrutledge -[Standard Base Documentation]: ../2-structured/project-setup/base-documentation.md -[Communication Tooling]: ../2-structured/project-setup/communication-tooling.md +[Standard Base Documentation]: ../2-structured/base-documentation.md +[Communication Tooling]: ../2-structured/communication-tooling.md [Trusted Committer]: ../2-structured/trusted-committer.md [Core Team]: ../2-structured/core-team.md diff --git a/patterns/2-structured/project-setup/issue-tracker.md b/patterns/2-structured/issue-tracker.md similarity index 100% rename from patterns/2-structured/project-setup/issue-tracker.md rename to patterns/2-structured/issue-tracker.md diff --git a/patterns/2-structured/project-setup/README.md b/patterns/2-structured/project-setup/README.md new file mode 100644 index 000000000..b4045fc26 --- /dev/null +++ b/patterns/2-structured/project-setup/README.md @@ -0,0 +1,3 @@ +# Files moved + +Files from this folder were moved [here](../). diff --git a/patterns/2-structured/release-process.md b/patterns/2-structured/release-process.md index 9ee5188aa..ae46068fd 100644 --- a/patterns/2-structured/release-process.md +++ b/patterns/2-structured/release-process.md @@ -53,7 +53,7 @@ A good example of quality release notes can be found [here](https://github.com/j 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. +Release notes are also a great opportunity to [praise participants](praise-participants.md)! As we know, [documentation is extremely important](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 diff --git a/patterns/2-structured/repository-activity-score.md b/patterns/2-structured/repository-activity-score.md index 27421a6ae..dae8f3e2b 100644 --- a/patterns/2-structured/repository-activity-score.md +++ b/patterns/2-structured/repository-activity-score.md @@ -115,7 +115,7 @@ The repository activity score is a simple calculation based on the GitHub API. I ## Known Instances * Used in SAP's InnerSource project portal to define the default order of the InnerSource projects. It was first created in July 2020 and is fine-tuned and updated frequently ever since. When proposed to the InnerSource Commons in July 2020, this pattern emerged. Also see [Michael Graf & Harish B (SAP) at ISC.S11 - The Unexpected Path of Applying InnerSource Patterns](https://www.youtube.com/watch?v=6r9QOw9dcQo&list=PLCH-i0B0otNQZQt_QzGR9Il_kE4C6cQRy&index=6). -* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./project-setup/base-documentation.md) and the [InnerSource License](./innersource-license.md). +* Airbus took a lot of inspiration from this pattern to create an "InnerSource score" that combines the activity score together with checks from the [Standard Base Documentation](./base-documentation.md) and the [InnerSource License](./innersource-license.md). ## Status diff --git a/patterns/2-structured/project-setup/templates/COMMUNICATION-template.md b/patterns/2-structured/templates/COMMUNICATION-template.md similarity index 100% rename from patterns/2-structured/project-setup/templates/COMMUNICATION-template.md rename to patterns/2-structured/templates/COMMUNICATION-template.md diff --git a/patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md b/patterns/2-structured/templates/CONTRIBUTING-template.md similarity index 100% rename from patterns/2-structured/project-setup/templates/CONTRIBUTING-template.md rename to patterns/2-structured/templates/CONTRIBUTING-template.md diff --git a/patterns/2-structured/project-setup/templates/README-template.md b/patterns/2-structured/templates/README-template.md similarity index 100% rename from patterns/2-structured/project-setup/templates/README-template.md rename to patterns/2-structured/templates/README-template.md diff --git a/translation/ja/patterns/base-documentation.md b/translation/ja/patterns/base-documentation.md index b7634e15c..95e9f3412 100644 --- a/translation/ja/patterns/base-documentation.md +++ b/translation/ja/patterns/base-documentation.md @@ -56,7 +56,7 @@ * プロジェクトにあなたの修正をサブミットする方法 * 修正が行われた場合、変更が取り込まれるまでに必要な所要時間に関する情報 -![Brief picture of README.md and CONTRIBUTING.md content](../../../patterns/2-structured/project-setup/assets/base\_docs\_drawing.png) +![Brief picture of README.md and CONTRIBUTING.md content](../../../assets/img/standard-base-documentation/base_docs_drawing.png) 様々なオープンソースプロジェクトにおいて、 `README.md` の書き方や、 `CONTRIBUTING.md` ファイルにどのような情報を含めるべきかについての良い例がたくさんあります。[How to write a readme that rocks](https://m.dotdev.co/how-to-write-a-readme-that-rocks-bc29f279611a), [Open Source Guide from GitHub](https://opensource.guide/) や書籍 [Producing Open Source](https://producingoss.com/en/producingoss.html)などのページには、どのような情報を提供すべきなのかについての貴重な情報が掲載されています。Producing Open Source には、良い README を書くための章はありませんが、[Getting Started chapter](https://producingoss.com/en/producingoss.html#starting-from-what-you-have) には、ホストチームのメンバー、ユーザー、コントリビューターが必要とするもののかなり広範なリストがあります。インナーソースのプロジェクトは、おそらく最初からこれらの側面のすべてをカバーする必要はありませんが、リスト自体は README.md がカバーできるものを想起するために有効です。 このパターンには、すぐに始められるように、2つの非常に基本的なテンプレートが付属しています。[README-template.md](../templates/README-template.md) と [CONTRIBUTING-template.md](../templates/CONTRIBUTING-template.md) をご参照ください