From 9dc2206a422dd1fc4038d3356eafbe16a57c6fd8 Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 05:51:04 -0700 Subject: [PATCH 01/12] content: expand InnerSource and AI section with agentic coding topics Add content from ispo-working-group#200: agentic/vibe coding, agent teams, future of software reuse, context size constraints, agent skills for enterprise standards, emerging standards (MCP, A2A, agents.md), AI slop risks, and short-term speed vs long-term quality tradeoffs. Co-Authored-By: Claude Opus 4.6 (1M context) --- innersource-and-ai/authors.md | 2 ++ innersource-and-ai/innersource-and-ai.md | 10 ++++++---- innersource-and-ai/risks-and-guardrails.md | 8 ++++++++ innersource-and-ai/shaping-for-ai.md | 16 ++++++++++++++++ .../why-innersource-matters-with-ai.md | 12 ++++++++++-- 5 files changed, 42 insertions(+), 6 deletions(-) diff --git a/innersource-and-ai/authors.md b/innersource-and-ai/authors.md index 16d55c6..fa5b0a1 100644 --- a/innersource-and-ai/authors.md +++ b/innersource-and-ai/authors.md @@ -5,6 +5,8 @@ Chronological order: * InnerSource Program Office (ISPO) Working Group, [InnerSource Commons](https://innersourcecommons.org/). +* Guilherme Dellagustin ([@dellagustin-sap](https://github.com/dellagustin-sap)) — framing of agentic coding, reuse futures, and emerging standards. +* Fei Wan — agent skills for enterprise standards. ## Reviewers diff --git a/innersource-and-ai/innersource-and-ai.md b/innersource-and-ai/innersource-and-ai.md index f77ad1a..f79abf3 100644 --- a/innersource-and-ai/innersource-and-ai.md +++ b/innersource-and-ai/innersource-and-ai.md @@ -1,13 +1,15 @@ # InnerSource and AI -Organizations are increasingly adopting AI in the workplace—from generative AI assistants to agentic coding tools that can write, refactor, and review code. This shift is changing how developers work: less time on typing code, more on defining requirements, guiding AI, and making sure systems are reliable and maintainable. For InnerSource program leads, the question is whether InnerSource still matters in this new landscape. +Organizations are increasingly adopting AI in the workplace—from generative AI assistants to agentic coding tools that can write, refactor, and review code. In many organizations, developers are now expected to do agentic coding (sometimes called "vibe coding"), where the role shifts from writing code to providing instructions in natural language and overseeing the work of automated coding agents. Some teams are going further, with multiple agents representing roles like quality engineering, project management, and frontend/backend development working in tandem and interacting directly with tools like issue trackers and source control platforms. + +This shift raises important questions: does software reuse still matter when AI can regenerate capabilities on demand? How do you maintain quality when code is produced at unprecedented speed? For InnerSource program leads, the question is whether InnerSource still matters in this new landscape. It does. InnerSource is potentially *more* important than ever. Shared repositories, clear boundaries, documentation, and collaborative practices help AI systems—and the people using them—work with the right context, reuse existing components, and keep quality high. This section explains why InnerSource matters when adopting AI, how to shape your repositories and practices for AI-assisted development, and what risks and guardrails to keep in mind. The following articles in this section go deeper: -- [Why InnerSource Matters When Adopting AI](why-innersource-matters-with-ai.md) — Relevance of InnerSource in an AI-augmented world, reuse, and production readiness. -- [Shaping Repositories and Practices for AI](shaping-for-ai.md) — Repository design, documentation, and workflow integration so both humans and AI can contribute effectively. -- [Risks and Guardrails](risks-and-guardrails.md) — Balancing speed with safety, the role of code review, and organizational best practices for AI use. +- [Why InnerSource Matters When Adopting AI](why-innersource-matters-with-ai.md) — Relevance of InnerSource in an AI-augmented world, reuse, the future of software development, and production readiness. +- [Shaping Repositories and Practices for AI](shaping-for-ai.md) — Repository design, documentation, agent skills, emerging standards, and workflow integration so both humans and AI can contribute effectively. +- [Risks and Guardrails](risks-and-guardrails.md) — Balancing speed with safety, mitigating AI slop, the role of code review, and organizational best practices for AI use. AI tooling and practices are evolving quickly. This section will be updated as the community learns more and as survey and research data become available. If you are new to InnerSource, we recommend starting with [Getting Started with InnerSource](http://www.oreilly.com/programming/free/getting-started-with-innersource.csp) and the [Introduction](/introduction/introduction.md) to this book. diff --git a/innersource-and-ai/risks-and-guardrails.md b/innersource-and-ai/risks-and-guardrails.md index ab91dad..5f48014 100644 --- a/innersource-and-ai/risks-and-guardrails.md +++ b/innersource-and-ai/risks-and-guardrails.md @@ -4,6 +4,14 @@ AI is the ultimate InnerSource contributor. Like any external contributor, AI ag Adopting AI without these guardrails can deliver short-term gains in speed and productivity, but at the cost of long-term risks to quality, security, and maintainability. The good news: if your organization has built a strong InnerSource culture, you already have the foundations in place. +## Short-term speed vs. long-term risk + +AI coding tools can deliver impressive short-term productivity gains. The risk is that teams take on more risk than they realize—releasing AI-generated content with fewer human reviews, skipping tests, or accepting code they do not fully understand. These gains can erode over time as technical debt, security vulnerabilities, and maintenance burden accumulate. InnerSource practices like mandatory code review, clear ownership, and contribution guidelines act as a natural brake on this tendency, ensuring that speed does not come at the expense of reliability. + +## Mitigating AI slop + +"AI slop" refers to low-quality, generic, or incorrect content produced by AI systems without adequate human oversight. In a development context, this can mean boilerplate code that does not fit the project's conventions, misleading documentation, or subtly incorrect implementations. InnerSource's emphasis on transparency—keeping things traceable and open for inspection—directly mitigates this risk. When contributions (whether from humans or AI) go through visible review processes in shared repositories, quality issues are caught earlier and patterns of slop become visible to the community. + ## Transparency and stakeholder involvement Involving stakeholders and keeping development transparent supports responsible AI deployment. When decisions about tools, patterns, and policies are visible and discussable, teams can align on what is acceptable and what is not. This aligns with InnerSource principles of openness and collaboration and helps prevent AI from being used in ways that conflict with organizational values or compliance requirements. diff --git a/innersource-and-ai/shaping-for-ai.md b/innersource-and-ai/shaping-for-ai.md index bb62eb2..acc44a2 100644 --- a/innersource-and-ai/shaping-for-ai.md +++ b/innersource-and-ai/shaping-for-ai.md @@ -18,4 +18,20 @@ Playbooks that describe how to contribute—and what to avoid—benefit both hum InnerSource can be integrated directly into coding workflows through skills, plugins, and tooling. When reuse and contribution are part of the daily environment—for example, by suggesting existing InnerSource components when starting a new feature—both developers and AI-assisted flows are more likely to reuse rather than duplicate. This is an area of active development; program leads can work with their tooling and platform teams to explore how to surface InnerSource projects and contribution paths where developers (and their tools) already work. +## Agent skills and enterprise standards + +A particularly promising approach is using agent skills to codify enterprise standards and best practices. Rather than documenting standards in wikis that developers must find and follow manually, organizations can encode them as skills that coding agents use directly. When an agent starts work, it can automatically apply the organization's coding standards, security policies, and architectural guidelines. This makes InnerSource contribution guidelines machine-readable and enforceable at the point of development. + +The [Agent Skills](https://agentskills.io/home) open standard provides a framework for packaging and sharing these capabilities. InnerSource programs can maintain shared skill libraries that any team's agents can use, extending the InnerSource model from shared code to shared agent behaviors. + +## Emerging standards and protocols + +Several open standards are emerging that are relevant to InnerSource programs adopting agentic workflows: + +- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) — A standard for connecting AI agents to external tools and data sources, enabling agents to interact with development infrastructure like issue trackers, CI/CD systems, and code review platforms. +- [Agent2Agent (A2A)](https://a2a-protocol.org/latest/) — A protocol for communication between AI agents, supporting scenarios where multiple specialized agents collaborate on development tasks. +- [agents.md](https://agents.md/) — A standard for describing how AI agents should interact with a repository, similar to how CONTRIBUTING.md guides human contributors. + +InnerSource program leads should monitor these standards as they mature. Organizations that adopt them early can shape how agent-to-agent and agent-to-repository interactions work across team boundaries, reinforcing InnerSource collaboration patterns at the tooling level. + For more on infrastructure and tooling in InnerSource, see [Tooling](/tooling/innersource-tooling.md) and [Infrastructure](/infrastructure/infrastructure.md). diff --git a/innersource-and-ai/why-innersource-matters-with-ai.md b/innersource-and-ai/why-innersource-matters-with-ai.md index c079bc4..4f5933e 100644 --- a/innersource-and-ai/why-innersource-matters-with-ai.md +++ b/innersource-and-ai/why-innersource-matters-with-ai.md @@ -6,13 +6,21 @@ AI and agentic coding are changing how development work gets done. Developers sp When many teams use AI to generate or modify code, the risk of duplication and inconsistency grows. InnerSource encourages shared building blocks and a single place to contribute improvements. That reduces waste and keeps quality consistent across the organization. The demand for software architecture and orchestration skills is also rising: understanding system boundaries, interfaces, and processes is essential for building valuable, reliable AI-assisted systems. InnerSource’s emphasis on transparency, documentation, and community aligns with this need. +## The shifting role of the developer + +Agentic coding—sometimes called “vibe coding”—is changing what it means to be a software developer. The role is shifting from one that writes code to one that provides instructions in natural language and oversees the work of automated agents. Teams are beginning to deploy agent teams where specialized agents handle quality engineering, project management, frontend, and backend work, interacting directly with tools like Jira and GitHub. + +This makes software architecture and orchestration skills more important than ever. Understanding system boundaries, interfaces, and integration points is essential when you are guiding agents rather than typing code yourself. InnerSource's emphasis on clear ownership, well-documented interfaces, and collaborative governance gives developers and their agents the structure they need to operate effectively across team boundaries. + ## Reducing context for AI -AI systems and coding agents work best when they have a well-scoped, well-boundaried context. InnerSource projects that are clearly scoped—with explicit interfaces and a clear purpose—give AI a manageable surface area. That improves reliability and reduces the chance of AI “hallucinating” or misusing code from outside the intended scope. Shaping your repositories for both humans and AI is a theme we explore in [Shaping Repositories and Practices for AI](shaping-for-ai.md). +AI systems and coding agents work best when they have a well-scoped, well-boundaried context. InnerSource projects that are clearly scoped—with explicit interfaces and a clear purpose—give AI a manageable surface area. That improves reliability and reduces the chance of AI “hallucinating” or misusing code from outside the intended scope. Context size remains a practical impediment: current models have limits on how much code and conversation history they can process at once, which makes well-boundaried, modular repositories even more valuable. Shaping your repositories for both humans and AI is a theme we explore in [Shaping Repositories and Practices for AI](shaping-for-ai.md). ## Reuse and avoiding duplication -Reuse at the service or component level is especially valuable when many teams use AI to generate code. Without shared standards and shared repos, each team may produce similar solutions in isolation. InnerSource fosters reuse and cost sharing across units, which in turn supports sustainability and efficiency. This is the same benefit InnerSource has always offered; in an AI-augmented world, it becomes harder to ignore. +The ease of generating software with AI puts the role of software reuse in question. When a coding agent can rewrite any capability on demand, why reuse an existing component? The answer is that reuse at the service or component level still matters—especially for services that carry their own system of records, compliance requirements, and organizational governance. Rewriting these introduces risk and duplication that AI speed does not offset. + +Without shared standards and shared repos, each team may produce similar solutions in isolation. InnerSource fosters reuse and cost sharing across units, which in turn supports sustainability and efficiency. Reusable InnerSource components can also reduce the cost of AI adoption: well-maintained shared libraries mean agents spend fewer tokens and less compute regenerating solutions that already exist. This is the same benefit InnerSource has always offered; in an AI-augmented world, it becomes harder to ignore. ## Platforms ready for InnerSource From 765ff8d2456c722345e8bf723cf09a5eda74e88f Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 07:23:33 -0700 Subject: [PATCH 02/12] fix: link to introduction --- innersource-and-ai/innersource-and-ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/innersource-and-ai/innersource-and-ai.md b/innersource-and-ai/innersource-and-ai.md index f79abf3..0c1aa23 100644 --- a/innersource-and-ai/innersource-and-ai.md +++ b/innersource-and-ai/innersource-and-ai.md @@ -12,4 +12,4 @@ The following articles in this section go deeper: - [Shaping Repositories and Practices for AI](shaping-for-ai.md) — Repository design, documentation, agent skills, emerging standards, and workflow integration so both humans and AI can contribute effectively. - [Risks and Guardrails](risks-and-guardrails.md) — Balancing speed with safety, mitigating AI slop, the role of code review, and organizational best practices for AI use. -AI tooling and practices are evolving quickly. This section will be updated as the community learns more and as survey and research data become available. If you are new to InnerSource, we recommend starting with [Getting Started with InnerSource](http://www.oreilly.com/programming/free/getting-started-with-innersource.csp) and the [Introduction](/introduction/introduction.md) to this book. +AI tooling and practices are evolving quickly. This section will be updated as the community learns more and as survey and research data become available. If you are new to InnerSource, we recommend starting with [Getting Started with InnerSource](http://www.oreilly.com/programming/free/getting-started-with-innersource.csp) and the [Introduction](../introduction/introduction.md) to this book. From e05673b3a5b9b503bb2f9ee6499258eb61c4a52b Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 07:27:58 -0700 Subject: [PATCH 03/12] fix: link to introduction --- innersource-and-ai/innersource-and-ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/innersource-and-ai/innersource-and-ai.md b/innersource-and-ai/innersource-and-ai.md index 0c1aa23..9775917 100644 --- a/innersource-and-ai/innersource-and-ai.md +++ b/innersource-and-ai/innersource-and-ai.md @@ -12,4 +12,4 @@ The following articles in this section go deeper: - [Shaping Repositories and Practices for AI](shaping-for-ai.md) — Repository design, documentation, agent skills, emerging standards, and workflow integration so both humans and AI can contribute effectively. - [Risks and Guardrails](risks-and-guardrails.md) — Balancing speed with safety, mitigating AI slop, the role of code review, and organizational best practices for AI use. -AI tooling and practices are evolving quickly. This section will be updated as the community learns more and as survey and research data become available. If you are new to InnerSource, we recommend starting with [Getting Started with InnerSource](http://www.oreilly.com/programming/free/getting-started-with-innersource.csp) and the [Introduction](../introduction/introduction.md) to this book. +AI tooling and practices are evolving quickly. This section will be updated as the community learns more and as survey and research data become available. If you are new to InnerSource, we recommend starting with [an Introdution to InnerSource](https://innersourcecommons.org/learn/learning-path/introduction/) and the [Introduction](../introduction/introduction.md) to this book. From 9d7b309307603e2d72587ea5862283e7b85cc1f2 Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:06:19 -0700 Subject: [PATCH 04/12] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- innersource-and-ai/innersource-and-ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/innersource-and-ai/innersource-and-ai.md b/innersource-and-ai/innersource-and-ai.md index 9775917..05b49b3 100644 --- a/innersource-and-ai/innersource-and-ai.md +++ b/innersource-and-ai/innersource-and-ai.md @@ -12,4 +12,4 @@ The following articles in this section go deeper: - [Shaping Repositories and Practices for AI](shaping-for-ai.md) — Repository design, documentation, agent skills, emerging standards, and workflow integration so both humans and AI can contribute effectively. - [Risks and Guardrails](risks-and-guardrails.md) — Balancing speed with safety, mitigating AI slop, the role of code review, and organizational best practices for AI use. -AI tooling and practices are evolving quickly. This section will be updated as the community learns more and as survey and research data become available. If you are new to InnerSource, we recommend starting with [an Introdution to InnerSource](https://innersourcecommons.org/learn/learning-path/introduction/) and the [Introduction](../introduction/introduction.md) to this book. +AI tooling and practices are evolving quickly. This section will be updated as the community learns more and as survey and research data become available. If you are new to InnerSource, we recommend starting with [an Introduction to InnerSource](https://innersourcecommons.org/learn/learning-path/introduction/) and the [Introduction](../introduction/introduction.md) to this book. From f5af69a3457bef513b0c3d2488cae224e067b2c5 Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:06:41 -0700 Subject: [PATCH 05/12] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- innersource-and-ai/shaping-for-ai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/innersource-and-ai/shaping-for-ai.md b/innersource-and-ai/shaping-for-ai.md index acc44a2..cd2ce08 100644 --- a/innersource-and-ai/shaping-for-ai.md +++ b/innersource-and-ai/shaping-for-ai.md @@ -34,4 +34,4 @@ Several open standards are emerging that are relevant to InnerSource programs ad InnerSource program leads should monitor these standards as they mature. Organizations that adopt them early can shape how agent-to-agent and agent-to-repository interactions work across team boundaries, reinforcing InnerSource collaboration patterns at the tooling level. -For more on infrastructure and tooling in InnerSource, see [Tooling](/tooling/innersource-tooling.md) and [Infrastructure](/infrastructure/infrastructure.md). +For more on infrastructure and tooling in InnerSource, see [Tooling](../tooling/innersource-tooling.md) and [Infrastructure](../infrastructure/infrastructure.md). From 7d89ebb0bdd0ac57ff3d40c1f56f3b4b11d14b56 Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 18:50:50 -0700 Subject: [PATCH 06/12] feat: add linkcheckers lychee/mdbook fix: broken links chore: improve clarity --- .lycheeignore | 9 ++++ CONTRIBUTING.md | 5 +- README.md | 11 ++--- SUMMARY.md | 7 ++- book.toml | 2 + governance/governance.md | 2 +- infrastructure/basics.md | 4 +- innersource-and-ai/shaping-for-ai.md | 2 +- introduction/framework.md | 4 +- lychee.toml | 8 ++++ scripts/install-mdbook.sh | 6 +++ scripts/lychee-book.sh | 70 ++++++++++++++++++++++++++++ tooling/authors.md | 2 +- tooling/github-configuration.md | 2 +- tooling/innersource-tooling.md | 2 +- translations/gl/README.md | 2 +- 16 files changed, 117 insertions(+), 21 deletions(-) create mode 100644 .lycheeignore create mode 100644 lychee.toml create mode 100755 scripts/lychee-book.sh diff --git a/.lycheeignore b/.lycheeignore new file mode 100644 index 0000000..94cbe2c --- /dev/null +++ b/.lycheeignore @@ -0,0 +1,9 @@ +# Pages excluded from link checking (see scripts/lychee-book.sh) +# print.html aggregates the whole book and repeats links; excluding it is required. +^https?://[^/]+/print\.html +# External sites that block or throttle link checkers +https://pixabay.com/users/bru-no-1161770/ +https://pixabay.com/service/license-summary/ +https://www.sap.com/ +# Built book may serve this chapter at README.html or index.html; ignore if 404 +^https?://[^/]+/measuring/gqm_example/README\.html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b6681a0..e3c4274 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,7 @@ This book uses the [Goal-Question-Metric] approach to documenting InnerSource me The full graph of relationships is visible in this [graph]. Add in your scenarios by copying this [goal template], [question template], and/or [metric template], filling them out, and submitting them in pull request. -After successful merge, a [Trusted Committer](https://github.com/orgs/InnerSourceCommons/teams/ispo-working-group-trusted-committers) will manually[^1] add those to the [graph]. +After successful merge, a [Trusted Committer](https://github.com/orgs/InnerSourceCommons/teams/ispo-working-group-trusted-committers) will manually add those to the [graph]. If interested, feel free to [edit the MermaidJS source] of the graph on your own! By adding in your scenarios to the graph, you will be able to see how others approach and interact with them. @@ -33,9 +33,6 @@ You may get new ideas of what metrics answer the questions you have or what addi When using titles in Markdown, use # for main title, ## for the second header title, etc. It's just to follow the same style :). -[^1]: [#37](https://github.com/InnerSourceCommons/managing-inner-source-projects/issues/37) will automate the addition of new goals, questions, and metrics to the graph. -At that time this manual step will no longer be needed. - [Goal-Question-Metric]: https://en.wikipedia.org/wiki/GQM [goals]: https://github.com/InnerSourceCommons/managing-inner-source-projects/tree/main/measuring/goals [questions]: https://github.com/InnerSourceCommons/managing-inner-source-projects/tree/main/measuring/questions diff --git a/README.md b/README.md index 19d633d..3cdff10 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Managing InnerSource Projects book -![Managing InnerSource Projects](managing-innersource-projects-cover.jpg) +![Managing InnerSource Projects](./managing-innersource-projects-cover.jpg) ## What is this book about? @@ -40,9 +40,9 @@ Come join us and contribute! ## How Do We Structure Goals, Questions, and Metrics? Review the [Goal-Question-Metric Approach](./measuring/gqm.md) to further understand how we structure goals, questions, and metrics. -Review [GQM use cases and user journeys](./measuring/gqm_example/README.md) to guide their development. +Review [GQM use cases and user journeys](measuring/gqm_example/README.md) to guide their development. -We document goals, questions, and metrics in separate folders in the [measuring](./measuring) directory. +We document goals, questions, and metrics in separate folders in the [measuring](./measuring/index.md) directory. You can browse all goals, questions, and metrics in [graph format](./measuring/use_gqm.md). Add in your own scenarios to the graph! @@ -60,13 +60,12 @@ Each chapter in the book is authored and reviewed by different people. That info be found at the beginning of each chapter. This initiative is fostered by the [ISPO Working Group]. For further questions, please contact us in [Slack](https://innersourcecommons.org/slack)! -The book cover was created by [Sebastian Spier](https://spier.hu), using an image by user [Bru-nO](https://pixabay.com/photos/measure-unit-of-measure-meterstab-2737004/), available under the [Pixabay License](https://pixabay.com/service/license/). +The book cover was created by [Sebastian Spier](https://spier.hu), using an image by user [Bru-nO](https://pixabay.com/users/bru-no-1161770/), available under the [Pixabay License](https://pixabay.com/service/license-summary/). All of the content found in this repository is licensed [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). -Please see [LICENSE.txt] in this repository for the full text of the license. +Please see [LICENSE.txt](https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/LICENSE.txt) in this repository for the full text of the license. [Bitergia]: https://bitergia.com/ [ISPO Working Group]: https://innersourcecommons.org/community/#ispo [InnerSource Commons]: https://innersourcecommons.org/ [InnerSource Patterns]: https://patterns.innersourcecommons.org/ -[LICENSE.txt]: ./LICENSE.txt diff --git a/SUMMARY.md b/SUMMARY.md index be7fb86..7a07996 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,6 +1,7 @@ # Summary * [Summary](README.md) +* [Contributing](CONTRIBUTING.md) * [Introduction](introduction/introduction.md) * [Scenarios](introduction/scenarios.md) * [Framework](introduction/framework.md) @@ -15,19 +16,23 @@ * [Goals](measuring/goals/index.md) * [Find InnerSource Projects](measuring/goals/find-projects.md) * [Reduce Duplication](measuring/goals/reduce-duplication.md) + * [GQM Goal Template](measuring/goals/gqm_goal_template.md) * [Questions](measuring/questions/index.md) - * [What is the InnerSource Adoption Trend?](measuring/questions/adoption-trend.md) + * [What is the InnerSource Adoption Trend?](measuring/questions/adoption-trend.md) * [Who contributes to the InnerSource project?](measuring/questions/who-contributes.md) * [Who Uses](measuring/questions/who-uses.md) + * [GQM Question Template](measuring/questions/gqm_question_template.md) * [Metrics](measuring/metrics/index.md) * [Code Contributions](measuring/metrics/code-contributions.md) * [Contribution Distance](measuring/metrics/contribution-distance.md) * [Number of InnerSource repositories](measuring/metrics/number-of-innersource-repositories.md) * [Usage Count](measuring/metrics/usage-count.md) + * [GQM Metric Template](measuring/metrics/gqm_metric_template.md) * [Areas of Analysis](measuring/areas.md) * [Goal-Question-Metric Approach](measuring/gqm.md) * [Strategy](measuring/strategy.md) * [Examples of Interest](measuring/examples.md) + * [GQM Use Cases and User Journeys](measuring/gqm_example/README.md) * [References](measuring/references.md) * [Authors and Reviewers](measuring/authors.md) * [Governance](governance/governance.md) diff --git a/book.toml b/book.toml index 59c5dde..98bc640 100644 --- a/book.toml +++ b/book.toml @@ -23,3 +23,5 @@ giscus.crossorigin = "anonymous" # Required for correct asset and 404 paths on GitHub Pages (project site and PR preview subpaths). site-url = "/managing-innersource-projects/" additional-js = ["mermaid.min.js", "mermaid-init.js"] + +[output.linkcheck2] \ No newline at end of file diff --git a/governance/governance.md b/governance/governance.md index 95a15ca..cdec84f 100644 --- a/governance/governance.md +++ b/governance/governance.md @@ -250,7 +250,7 @@ organization and its context and find other goals InnerSource may contribute towards. Then communicate it and get as much air cover from your executives as you can. -For how governance and transparency support responsible use of AI in development, see [InnerSource and AI](/innersource-and-ai/innersource-and-ai.md), in particular [Risks and Guardrails](/innersource-and-ai/risks-and-guardrails.md). +For how governance and transparency support responsible use of AI in development, see [InnerSource and AI](../innersource-and-ai/innersource-and-ai.md), in particular [Risks and Guardrails](../innersource-and-ai/risks-and-guardrails.md). [^1]: http://oss-watch.ac.uk/resources/governancemodels diff --git a/infrastructure/basics.md b/infrastructure/basics.md index a2531d8..15714de 100644 --- a/infrastructure/basics.md +++ b/infrastructure/basics.md @@ -147,7 +147,7 @@ and communication. Even when the developers are in face to face meetings, those tools should be used as they will leave traces of activity readable by others within the organization. -![Extended usual software development process](development_workflow_all.jpg) +![Extended usual software development process](./development_workflow_all.jpg) ## Communication Channels Infrastructure @@ -210,7 +210,7 @@ to their specific needs. The following is a potential architecture that could help when accessing the several data layers, from raw information to detailed visualizations. -![Monitoring Infrastructure](monitoring_infrastructure.jpg) +![Monitoring Infrastructure](./monitoring_infrastructure.jpg) * **Retrieval Platform**: this first part uses as input any of the data sources already mentioned. Version systems, mailing lists, tickets, diff --git a/innersource-and-ai/shaping-for-ai.md b/innersource-and-ai/shaping-for-ai.md index acc44a2..cd2ce08 100644 --- a/innersource-and-ai/shaping-for-ai.md +++ b/innersource-and-ai/shaping-for-ai.md @@ -34,4 +34,4 @@ Several open standards are emerging that are relevant to InnerSource programs ad InnerSource program leads should monitor these standards as they mature. Organizations that adopt them early can shape how agent-to-agent and agent-to-repository interactions work across team boundaries, reinforcing InnerSource collaboration patterns at the tooling level. -For more on infrastructure and tooling in InnerSource, see [Tooling](/tooling/innersource-tooling.md) and [Infrastructure](/infrastructure/infrastructure.md). +For more on infrastructure and tooling in InnerSource, see [Tooling](../tooling/innersource-tooling.md) and [Infrastructure](../infrastructure/infrastructure.md). diff --git a/introduction/framework.md b/introduction/framework.md index 757f6e2..4b397cb 100644 --- a/introduction/framework.md +++ b/introduction/framework.md @@ -34,7 +34,7 @@ Let's introduce the *InnerSource framework*. A core aspect of the InnerSource framework is the governance model. Good governance is essential for the success of any project, and InnerSource is no exception. -Pick the right [governance standards and model](/governance/governance.md) for your organization. +Pick the right [governance standards and model](../governance/governance.md) for your organization. ## Technical infrastructure @@ -115,4 +115,4 @@ Open measurement gives a lot of benefits for our InnerSource community: ## InnerSource and AI -Organizations adopting AI in the workplace—from generative AI assistants to agentic coding tools—can benefit from InnerSource in new ways. Shared repositories, clear boundaries, and collaborative practices help both humans and AI work with the right context and reuse. See the [InnerSource and AI](/innersource-and-ai/innersource-and-ai.md) section for why it matters, how to shape repositories and practices for AI, and what risks and guardrails to consider. +Organizations adopting AI in the workplace—from generative AI assistants to agentic coding tools—can benefit from InnerSource in new ways. Shared repositories, clear boundaries, and collaborative practices help both humans and AI work with the right context and reuse. See the [InnerSource and AI](../innersource-and-ai/innersource-and-ai.md) section for why it matters, how to shape repositories and practices for AI, and what risks and guardrails to consider. diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..3bc1ead --- /dev/null +++ b/lychee.toml @@ -0,0 +1,8 @@ +# Lychee config for checking the built mdbook served at http://localhost:3000/ +# Run: scripts/lychee-book.sh or: +# find book/html -name "*.html" -not -path "*/.cargo/*" -not -path "*/.git/*" -not -path "*/.rustup/*" -not -path "*/.github/*" -not -path "*/.claude/*" -not -path "*/.nwave/*" | lychee --base-url "http://localhost:3000/" --files-from - + +format = "detailed" +verbose = "info" +# Allow 2xx and 3xx (redirects) as success +accept = "100..=103,200..=399" diff --git a/scripts/install-mdbook.sh b/scripts/install-mdbook.sh index 06ab9f6..8f0c3c8 100755 --- a/scripts/install-mdbook.sh +++ b/scripts/install-mdbook.sh @@ -6,6 +6,7 @@ set -euo pipefail MDBOOK_VERSION="${MDBOOK_VERSION:-0.5.2}" MDBOOK_MERMAID_VERSION="${MDBOOK_MERMAID_VERSION:-0.17.0}" MDBOOK_EMBEDIFY_VERSION="${MDBOOK_EMBEDIFY_VERSION:-0.3.2}" +MDBOOK_LINKCHECK2_VERSION="${MDBOOK_LINKCHECK2_VERSION:-0.12.0}" RUST_TOOLCHAIN_VERSION="${RUST_TOOLCHAIN_VERSION:-1.91.1}" # Install into repo so CI and local use the same layout (avoids cross-device issues in act) @@ -23,9 +24,14 @@ fi rustup toolchain install "${RUST_TOOLCHAIN_VERSION}" --profile minimal rustup default "${RUST_TOOLCHAIN_VERSION}" +# https://github.com/rust-lang/mdBook cargo install --version "${MDBOOK_VERSION}" mdbook +# https://github.com/badboy/mdbook-mermaid cargo install --version "${MDBOOK_MERMAID_VERSION}" mdbook-mermaid +# https://github.com/rust-lang/mdbook-embedify cargo install --version "${MDBOOK_EMBEDIFY_VERSION}" mdbook-embedify +# https://github.com/Michael-F-Bryan/mdbook-linkcheck +cargo install --version "${MDBOOK_LINKCHECK2_VERSION}" mdbook-linkcheck2 echo "Done. To build the book, use the project mdbook (do not use your global 'mdbook'):" echo " ${CARGO_HOME}/bin/mdbook build" diff --git a/scripts/lychee-book.sh b/scripts/lychee-book.sh new file mode 100755 index 0000000..51f8e53 --- /dev/null +++ b/scripts/lychee-book.sh @@ -0,0 +1,70 @@ +#!/usr/bin/env bash +# Check all links in the built and served book with lychee. +# +# Prereqs: +# 1. Build the book: mdbook build +# 2. Serve the book: npx serve book -p 3000 +# 3. Install lychee: cargo install lychee +# +# Usage: ./scripts/lychee-book.sh [BASE_URL] +# BASE_URL defaults to http://localhost:3000/ +# +# Report shows which page contains each broken link (source page → failed URL). +# For the "Broken links by page" section, jq must be installed; otherwise only lychee's default output is shown. + +set -e + +BASE_URL="${1:-http://localhost:3000/}" +# Ensure base URL has no trailing slash for consistent resolution (lychee strips fragment) +BASE_URL="${BASE_URL%/}" + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +BOOK_DIR="${ROOT}/book" +JSON_REPORT="${ROOT}/.lychee-report.json" + +# Collect only the book's HTML (exclude vendored/cache dirs and nested book/html/). +# npx serve book -p 3000 serves BOOK_DIR at BASE_URL, so URLs are BASE_URL/. +# Required: exclude print.html (see .lycheeignore); it aggregates the whole book and repeats links. +set +e +find "$BOOK_DIR" -name "*.html" \ + -not -path "*/.cargo/*" \ + -not -path "*/.git/*" \ + -not -path "*/.rustup/*" \ + -not -path "*/.github/*" \ + -not -path "*/.claude/*" \ + -not -path "*/.nwave/*" \ + -not -path "*/html/*" \ + 2>/dev/null | while read -r f; do + # Convert path to URL: book/measuring/use_gqm.html -> BASE_URL/measuring/use_gqm.html + path="${f#"$BOOK_DIR/"}" + [[ "$path" == "print.html" ]] && continue + echo "${BASE_URL}/${path}" +done | lychee --no-progress -q --format json --output "$JSON_REPORT" --files-from - +lychee_exit=$? +set -e + +# Print report: for each broken link, show the page that contains it. +# Lychee uses "error_map" (source URL -> list of { url, status: { code } }); some versions use "fail_map". +echo "JSON_REPORT: $JSON_REPORT" +if [[ -f "$JSON_REPORT" ]]; then + errors="" + if command -v jq &>/dev/null; then + errors=$(jq -r '(.error_map // .fail_map // {}) | to_entries[] | "Page: \(.key)\n Broken:\n\(.value[] | " [\(.status.code)] \(.url)")"' "$JSON_REPORT" 2>/dev/null) + fi + if [[ -n "$errors" ]]; then + echo "" + echo "=== Broken links by page ===" + echo "$errors" + else + # Report has failures but we couldn't print them (no jq or jq failed); leave report for inspection + report_errors=$(jq -r '.errors // 0' "$JSON_REPORT" 2>/dev/null || echo "0") + if [[ "$report_errors" != "0" ]] && [[ "$report_errors" != "null" ]]; then + echo "" + echo "=== Broken links (report has $report_errors failure(s)); full report: $JSON_REPORT ===" + echo "Install jq to see 'Broken links by page' summary, or: cat $JSON_REPORT | jq '.error_map'" + fi + fi + rm -f "$JSON_REPORT" +fi + +exit "$lychee_exit" diff --git a/tooling/authors.md b/tooling/authors.md index 8024c95..7a7a970 100644 --- a/tooling/authors.md +++ b/tooling/authors.md @@ -9,4 +9,4 @@ (Chronological order) -- Guilherme Dellagustin ([SAP](https://sap.com/)) +- Guilherme Dellagustin ([SAP](https://www.sap.com/index.html)) diff --git a/tooling/github-configuration.md b/tooling/github-configuration.md index a8207ec..b6c7b48 100644 --- a/tooling/github-configuration.md +++ b/tooling/github-configuration.md @@ -218,4 +218,4 @@ Enabling Server Statistics in your GitHub Enterprise Server environment can prov ## Resources -- [Orgs and Teams Best Practices · GitHub](https://gist.github.com/rwnfoo/3e19747f6dc2c5b9cfb0ff9c89d834b4) +- [Organization and repository settings](#organization-setting) (in this guide) diff --git a/tooling/innersource-tooling.md b/tooling/innersource-tooling.md index 7f279ad..5348306 100644 --- a/tooling/innersource-tooling.md +++ b/tooling/innersource-tooling.md @@ -1,6 +1,6 @@ # InnerSource with GitHub -For how tooling and workflow integration support AI-assisted development and InnerSource together, see the [InnerSource and AI](/innersource-and-ai/innersource-and-ai.md) section, in particular [Shaping Repositories and Practices for AI](/innersource-and-ai/shaping-for-ai.md). +For how tooling and workflow integration support AI-assisted development and InnerSource together, see the [InnerSource and AI](../innersource-and-ai/innersource-and-ai.md) section, in particular [Shaping Repositories and Practices for AI](../innersource-and-ai/shaping-for-ai.md). ## Effective InnerSource Strategies and Configuration for GitHub diff --git a/translations/gl/README.md b/translations/gl/README.md index d4fbd95..1c04ef7 100644 --- a/translations/gl/README.md +++ b/translations/gl/README.md @@ -28,7 +28,7 @@ Se ten algunha pregunta, pode pórse en contacto con José Manrique López ou Da Grazas polo seu interese. -A portada do libro foi creada por [Sebastian Spier](https://spier.hu), a partir dunha imaxe do usuario [Bru-nO](https://pixabay.com/photos/measure-unit-of-measure-meterstab-2737004/), dispoñible baixo a [licenza Pixabay](https://pixabay.com/service/license/). +A portada do libro foi creada por [Sebastian Spier](https://spier.hu), a partir dunha imaxe do usuario [Bru-nO](https://pixabay.com/photos/measure-unit-of-measure-meterstab-2737004/), dispoñible baixo a [licenza Pixabay](https://pixabay.com/service/license-summary/). Todo o contido que se atopa neste repositorio ten licenza [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). From f29606c2a5d55cddd93c29db511950fdefbaff7c Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 19:19:08 -0700 Subject: [PATCH 07/12] fix: reference warnings fix: caching and install logic fix: mdbook links failing from link check --- .github/workflows/mdbook.yml | 25 +++++++--------- measuring/references.md | 54 ++++++++++++++++++---------------- scripts/install-mdbook.sh | 25 +++++++++++++--- tooling/innersource-tooling.md | 28 +++++++++--------- 4 files changed, 74 insertions(+), 58 deletions(-) diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml index f247864..b781e21 100644 --- a/.github/workflows/mdbook.yml +++ b/.github/workflows/mdbook.yml @@ -44,16 +44,16 @@ jobs: restore-keys: | ${{ runner.os }}-cargo-registry- - - name: Cache Rust toolchains + # Cache full RUSTUP_HOME (rustc + toolchain + settings) so rustup does minimal work on restore. + - name: Cache Rust toolchain (rustc) uses: actions/cache@v4 with: - path: | - ${{ env.RUSTUP_HOME }}/toolchains - ${{ env.RUSTUP_HOME }}/update-hashes + path: ${{ env.RUSTUP_HOME }} key: ${{ runner.os }}-rust-toolchain-${{ hashFiles('scripts/install-mdbook.sh') }} restore-keys: | ${{ runner.os }}-rust-toolchain- + # Exact key only (no restore-keys) so we never restore a bin/ missing a tool (e.g. linkcheck2). - name: Cache installed mdBook binaries id: mdbook-cache uses: actions/cache@v4 @@ -61,11 +61,9 @@ jobs: path: | ${{ env.CARGO_HOME }}/bin key: ${{ runner.os }}-mdbook-bin-${{ hashFiles('scripts/install-mdbook.sh') }} - restore-keys: | - ${{ runner.os }}-mdbook-bin- + # Script skips install when cached binaries already match versions in install-mdbook.sh - name: Install mdBook - if: steps.mdbook-cache.outputs.cache-hit != 'true' run: bash scripts/install-mdbook.sh env: REPO_ROOT: ${{ github.workspace }} @@ -104,17 +102,17 @@ jobs: restore-keys: | ${{ runner.os }}-cargo-registry- - - name: Cache Rust toolchains + # Cache full RUSTUP_HOME (rustc + toolchain + settings) so rustup does minimal work on restore. + - name: Cache Rust toolchain (rustc) if: github.event.action != 'closed' uses: actions/cache@v4 with: - path: | - ${{ env.RUSTUP_HOME }}/toolchains - ${{ env.RUSTUP_HOME }}/update-hashes + path: ${{ env.RUSTUP_HOME }} key: ${{ runner.os }}-rust-toolchain-${{ hashFiles('scripts/install-mdbook.sh') }} restore-keys: | ${{ runner.os }}-rust-toolchain- + # Exact key only (no restore-keys) so we never restore a bin/ missing a tool (e.g. linkcheck2). - name: Cache installed mdBook binaries if: github.event.action != 'closed' id: mdbook-cache @@ -123,11 +121,10 @@ jobs: path: | ${{ env.CARGO_HOME }}/bin key: ${{ runner.os }}-mdbook-bin-${{ hashFiles('scripts/install-mdbook.sh') }} - restore-keys: | - ${{ runner.os }}-mdbook-bin- + # Script skips install when cached binaries already match versions in install-mdbook.sh - name: Install mdBook - if: github.event.action != 'closed' && steps.mdbook-cache.outputs.cache-hit != 'true' + if: github.event.action != 'closed' run: bash scripts/install-mdbook.sh env: REPO_ROOT: ${{ github.workspace }} diff --git a/measuring/references.md b/measuring/references.md index 779b087..0108a62 100644 --- a/measuring/references.md +++ b/measuring/references.md @@ -1,32 +1,34 @@ -[^1]: A pull request is the action of submitting a piece of for - reviewing. This term comes from the open source communities and was - basically raised by the collaborative way that GitHub works +# References -[^2]: Software modeling and measurement: the goal question metric - paradigm. Victor R. Basili +1. A pull request is the action of submitting a piece of work for + reviewing. This term comes from the open source communities and was + basically raised by the collaborative way that GitHub works. -[^3]: There are great talks and even handbooks around the Web stating - the goals of InnerSource. The proposed list of main goals does not - aim at being exhaustive, but an introduction to the InnerSource - context. This could be also seen as a summary of the following talks - and handbooks: “Getting Started with InnerSource. Keys to - collaboration and productivity inside your company” by Andy Oram. - “Inner Sourcing. Enterprise Lessons Learned from the Open Source - Community” by Jim Jagielski. And “Community Development Practices in - Corporate IT. InnerSource Fundamentals” by Guy Martin and Andrew - Aitken. +2. Software modeling and measurement: the goal question metric + paradigm. Victor R. Basili. -[^4]: “Best Kept Secrets of Peer Code Review” by Jason Cohen, Steven - Teleki, Eric Brown and others. +3. There are great talks and even handbooks around the Web stating + the goals of InnerSource. The proposed list of main goals does not + aim at being exhaustive, but an introduction to the InnerSource + context. This could be also seen as a summary of the following talks + and handbooks: "Getting Started with InnerSource. Keys to + collaboration and productivity inside your company" by Andy Oram. + "Inner Sourcing. Enterprise Lessons Learned from the Open Source + Community" by Jim Jagielski. And "Community Development Practices in + Corporate IT. InnerSource Fundamentals" by Guy Martin and Andrew + Aitken. -[^5]: These two are referenced in the great book “Software Development - Metrics” by David Nicolette. The third one, motivational aspects, - from our perspective, should be taken into account and being in this - same level, as specific actions can be carried out when building - InnerSource organizations as in the same way open source - organizations work this community building aspect +4. "Best Kept Secrets of Peer Code Review" by Jason Cohen, Steven + Teleki, Eric Brown and others. -[^6]: Software modeling and measurement: the goal question metric - paradigm. Victor R. Basili. +5. These two are referenced in the great book "Software Development + Metrics" by David Nicolette. The third one, motivational aspects, + from our perspective, should be taken into account and being in this + same level, as specific actions can be carried out when building + InnerSource organizations as in the same way open source + organizations work this community building aspect. -[^7]: Java vs JS case +6. Software modeling and measurement: the goal question metric + paradigm. Victor R. Basili. + +7. Java vs JS case. diff --git a/scripts/install-mdbook.sh b/scripts/install-mdbook.sh index 8f0c3c8..5aefa99 100755 --- a/scripts/install-mdbook.sh +++ b/scripts/install-mdbook.sh @@ -24,14 +24,31 @@ fi rustup toolchain install "${RUST_TOOLCHAIN_VERSION}" --profile minimal rustup default "${RUST_TOOLCHAIN_VERSION}" +# Skip install when binary exists and reports the expected version (e.g. from CI cache). +# All four tools (mdbook, mdbook-mermaid, mdbook-embedify, mdbook-linkcheck2) are checked. +# Install with --force when missing or version mismatch so we overwrite. +bin_dir="${CARGO_HOME}/bin" +has_version() { + [[ -x "${bin_dir}/$1" ]] && "${bin_dir}/$1" --version 2>/dev/null | grep -qF "$2" +} + +install_if_needed() { + local name=$1 version=$2 + if has_version "$name" "$version"; then + echo "$name $version already installed (cached), skipping." + else + cargo install --version "$version" "$name" --force + fi +} + # https://github.com/rust-lang/mdBook -cargo install --version "${MDBOOK_VERSION}" mdbook +install_if_needed mdbook "${MDBOOK_VERSION}" # https://github.com/badboy/mdbook-mermaid -cargo install --version "${MDBOOK_MERMAID_VERSION}" mdbook-mermaid +install_if_needed mdbook-mermaid "${MDBOOK_MERMAID_VERSION}" # https://github.com/rust-lang/mdbook-embedify -cargo install --version "${MDBOOK_EMBEDIFY_VERSION}" mdbook-embedify +install_if_needed mdbook-embedify "${MDBOOK_EMBEDIFY_VERSION}" # https://github.com/Michael-F-Bryan/mdbook-linkcheck -cargo install --version "${MDBOOK_LINKCHECK2_VERSION}" mdbook-linkcheck2 +install_if_needed mdbook-linkcheck2 "${MDBOOK_LINKCHECK2_VERSION}" echo "Done. To build the book, use the project mdbook (do not use your global 'mdbook'):" echo " ${CARGO_HOME}/bin/mdbook build" diff --git a/tooling/innersource-tooling.md b/tooling/innersource-tooling.md index 5348306..8ba0a54 100644 --- a/tooling/innersource-tooling.md +++ b/tooling/innersource-tooling.md @@ -22,19 +22,19 @@ for a perspective focused entirely on security. - [Pros and Cons of InnerSource Dedicated Environment](./github-strategy.md#pros-and-cons-of-innersource-dedicated-environment) - [Variations in how repository read access is distributed](./github-strategy.md#variations-in-how-repository-read-access-is-distributed) - [Conclusion: High Level Guideline](./github-strategy.md#conclusion-high-level-guideline) -- [GitHub InnerSource Configuration](./github-configuration.md/#github-innersource-configuration) - - [Enterprise Setting](./github-configuration.md/#enterprise-setting) - - [Repository policies](./github-configuration.md/#repository-policies) - - [Base permissions](./github-configuration.md/#base-permissions) - - [Repository creation](./github-configuration.md/#repository-creation) - - [Repository forking (Private / Internal)](./github-configuration.md/#repository-forking-private--internal) - - [Organization Setting](./github-configuration.md/#organization-setting) - - [Member privileges](./github-configuration.md/#member-privileges) - - [Base permissions](./github-configuration.md/#base-permissions-1) - - [Repository creation](./github-configuration.md/#repository-creation-1) - - [Repository forking](./github-configuration.md/#repository-forking) - - [GitHub Enterprise Server Setting](./github-configuration.md/#github-enterprise-server-setting) - - [GitHub Connect - Server statistics](./github-configuration.md/#github-connect---server-statistics) - - [Resources](./github-configuration.md/#resources) +- [GitHub InnerSource Configuration](./github-configuration.md#github-innersource-configuration) + - [Enterprise Setting](./github-configuration.md#enterprise-setting) + - [Repository policies](./github-configuration.md#repository-policies) + - [Base permissions](./github-configuration.md#base-permissions) + - [Repository creation](./github-configuration.md#repository-creation) + - [Repository forking (Private / Internal)](./github-configuration.md#repository-forking-private--internal) + - [Organization Setting](./github-configuration.md#organization-setting) + - [Member privileges](./github-configuration.md#member-privileges) + - [Base permissions](./github-configuration.md#base-permissions-1) + - [Repository creation](./github-configuration.md#repository-creation-1) + - [Repository forking](./github-configuration.md#repository-forking) + - [GitHub Enterprise Server Setting](./github-configuration.md#github-enterprise-server-setting) + - [GitHub Connect - Server statistics](./github-configuration.md#github-connect---server-statistics) + - [Resources](./github-configuration.md#resources) ### GitLab From d0df7007041515827872f040fb745360aca97b48 Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 19:37:17 -0700 Subject: [PATCH 08/12] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- scripts/lychee-book.sh | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/lychee-book.sh b/scripts/lychee-book.sh index 51f8e53..b9abe73 100755 --- a/scripts/lychee-book.sh +++ b/scripts/lychee-book.sh @@ -10,7 +10,7 @@ # BASE_URL defaults to http://localhost:3000/ # # Report shows which page contains each broken link (source page → failed URL). -# For the "Broken links by page" section, jq must be installed; otherwise only lychee's default output is shown. +# For the "Broken links by page" section, jq must be installed; otherwise the raw JSON report is kept for manual inspection. set -e @@ -47,6 +47,7 @@ set -e # Lychee uses "error_map" (source URL -> list of { url, status: { code } }); some versions use "fail_map". echo "JSON_REPORT: $JSON_REPORT" if [[ -f "$JSON_REPORT" ]]; then + delete_report=1 errors="" if command -v jq &>/dev/null; then errors=$(jq -r '(.error_map // .fail_map // {}) | to_entries[] | "Page: \(.key)\n Broken:\n\(.value[] | " [\(.status.code)] \(.url)")"' "$JSON_REPORT" 2>/dev/null) @@ -62,9 +63,12 @@ if [[ -f "$JSON_REPORT" ]]; then echo "" echo "=== Broken links (report has $report_errors failure(s)); full report: $JSON_REPORT ===" echo "Install jq to see 'Broken links by page' summary, or: cat $JSON_REPORT | jq '.error_map'" + delete_report=0 fi fi - rm -f "$JSON_REPORT" + if [[ "$delete_report" -eq 1 ]]; then + rm -f "$JSON_REPORT" + fi fi exit "$lychee_exit" From 760d62999379d6250bd97f6afa1ed53301d158ae Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 19:38:58 -0700 Subject: [PATCH 09/12] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3c4274..ce45f70 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,15 +3,15 @@ This book is built as a [Gitbook book](https://gitbook.com). This is written using [Markdown syntax](https://www.gitbook.com/book/gitbookio/markdown/). This is maintained under the [InnerSource Commons' GitHub account](https://github.com/innersourcecommons) in the -[Managing Inner Source Projects repository](https://github.com/innersourcecommons/managing-inner-source-projects). +[Managing Inner Source Projects repository](https://github.com/innersourcecommons/managing-innersource-projects). Thus you can follow the usual contribution process in GitHub through [Pull Requests](https://help.github.com/articles/about-pull-requests/). You can see for instance the pull requests open and closed at this point in time and for -this repository at https://github.com/innersourcecommons/managing-inner-source-projects/pulls . +this repository at https://github.com/innersourcecommons/managing-innersource-projects/pulls . If you want to share an idea, comment or feature request, you can also open an issue -in the [GitHub issues tracking for this repository](https://github.com/innersourcecommons/managing-inner-source-projects/issues). +in the [GitHub issues tracking for this repository](https://github.com/innersourcecommons/managing-innersource-projects/issues). Please be aware that all of your contributions will be opened by default and that those will be licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). @@ -34,11 +34,11 @@ You may get new ideas of what metrics answer the questions you have or what addi When using titles in Markdown, use # for main title, ## for the second header title, etc. It's just to follow the same style :). [Goal-Question-Metric]: https://en.wikipedia.org/wiki/GQM -[goals]: https://github.com/InnerSourceCommons/managing-inner-source-projects/tree/main/measuring/goals -[questions]: https://github.com/InnerSourceCommons/managing-inner-source-projects/tree/main/measuring/questions -[metrics]: https://github.com/InnerSourceCommons/managing-inner-source-projects/tree/main/measuring/metrics -[goal template]: https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/goals/gqm_goal_template.md -[question template]: https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/questions/gqm_question_template.md -[metric template]: https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/metrics/gqm_metric_template.md -[edit the MermaidJS source]: https://github.com/InnerSourceCommons/managing-inner-source-projects/edit/main/measuring/use_gqm.md -[graph]: https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/use_gqm.md +[goals]: https://github.com/InnerSourceCommons/managing-innersource-projects/tree/main/measuring/goals +[questions]: https://github.com/InnerSourceCommons/managing-innersource-projects/tree/main/measuring/questions +[metrics]: https://github.com/InnerSourceCommons/managing-innersource-projects/tree/main/measuring/metrics +[goal template]: https://github.com/InnerSourceCommons/managing-innersource-projects/blob/main/measuring/goals/gqm_goal_template.md +[question template]: https://github.com/InnerSourceCommons/managing-innersource-projects/blob/main/measuring/questions/gqm_question_template.md +[metric template]: https://github.com/InnerSourceCommons/managing-innersource-projects/blob/main/measuring/metrics/gqm_metric_template.md +[edit the MermaidJS source]: https://github.com/InnerSourceCommons/managing-innersource-projects/edit/main/measuring/use_gqm.md +[graph]: https://github.com/InnerSourceCommons/managing-innersource-projects/blob/main/measuring/use_gqm.md From 1fbb20541afbf69c75054e002d004506f9a3e832 Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 19:39:14 -0700 Subject: [PATCH 10/12] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3cdff10..b2e473d 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ For further questions, please contact us in [Slack](https://innersourcecommons.o The book cover was created by [Sebastian Spier](https://spier.hu), using an image by user [Bru-nO](https://pixabay.com/users/bru-no-1161770/), available under the [Pixabay License](https://pixabay.com/service/license-summary/). All of the content found in this repository is licensed [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). -Please see [LICENSE.txt](https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/LICENSE.txt) in this repository for the full text of the license. +Please see [LICENSE.txt](./LICENSE.txt) in this repository for the full text of the license. [Bitergia]: https://bitergia.com/ [ISPO Working Group]: https://innersourcecommons.org/community/#ispo From 5c97038a7df430eb537bc9224d31e166ec4c812e Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Wed, 18 Mar 2026 19:46:03 -0700 Subject: [PATCH 11/12] chore: set author to ISPO WG / ISC --- innersource-and-ai/authors.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/innersource-and-ai/authors.md b/innersource-and-ai/authors.md index fa5b0a1..16d55c6 100644 --- a/innersource-and-ai/authors.md +++ b/innersource-and-ai/authors.md @@ -5,8 +5,6 @@ Chronological order: * InnerSource Program Office (ISPO) Working Group, [InnerSource Commons](https://innersourcecommons.org/). -* Guilherme Dellagustin ([@dellagustin-sap](https://github.com/dellagustin-sap)) — framing of agentic coding, reuse futures, and emerging standards. -* Fei Wan — agent skills for enterprise standards. ## Reviewers From aae38bf18f29a31bda684ee6e005c42f4fdf03db Mon Sep 17 00:00:00 2001 From: Jeff Bailey <776901+jeffabailey@users.noreply.github.com> Date: Thu, 26 Mar 2026 12:56:06 -0700 Subject: [PATCH 12/12] fix: mdbook install\nfix: gqm build and links --- Makefile | 7 +++++++ README.md | 24 +++++++++++++++++++++ book.toml | 3 ++- measuring/use_gqm.md | 39 ++++++++++++++++++++++++----------- scripts/build.sh | 24 +++++++++++++++++++++ scripts/gqm_gen/index.test.ts | 18 +++++++++++++++- scripts/gqm_gen/index.ts | 39 +++++++++++++++++++++-------------- scripts/install-mdbook.sh | 5 +++-- scripts/serve.sh | 25 ++++++++++++++++++++++ 9 files changed, 153 insertions(+), 31 deletions(-) create mode 100644 Makefile create mode 100755 scripts/build.sh create mode 100755 scripts/serve.sh diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..8a4b1c6 --- /dev/null +++ b/Makefile @@ -0,0 +1,7 @@ +.PHONY: build serve + +build: + ./scripts/build.sh + +serve: + ./scripts/serve.sh diff --git a/README.md b/README.md index b2e473d..def3084 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,30 @@ Articles should be relatively short and self-contained so that they can be read Detailed explanation of InnerSource topics should go in the [InnerSource Patterns] book and be linked from the article here. Think of the articles in this book like either a conversational introduction/summary to a pattern or possible a journey showing how multiple patterns can be used together in an InnerSource Program. +## Building the Book Locally + +The book is built with [mdBook](https://rust-lang.github.io/mdBook/). +You don't need to install anything manually — the helper scripts handle everything. + +**Build the book** (output goes to `book/`): + +```sh +make build +``` + +**Live-preview with auto-reload** (opens a local web server): + +```sh +make serve +``` + +On the first run, the scripts will automatically install Rust and mdBook into the +repo-local `.cargo/` and `.rustup/` directories (these are git-ignored). +Subsequent runs reuse the existing install and start immediately. + +> **Windows users:** Run these scripts in **Git Bash** (included with +> [Git for Windows](https://gitforwindows.org/)) or in WSL. + ## Who can contribute? This book is a work in progress where anyone is more than welcome to contribute diff --git a/book.toml b/book.toml index 98bc640..2fc2f21 100644 --- a/book.toml +++ b/book.toml @@ -24,4 +24,5 @@ giscus.crossorigin = "anonymous" site-url = "/managing-innersource-projects/" additional-js = ["mermaid.min.js", "mermaid-init.js"] -[output.linkcheck2] \ No newline at end of file +[output.linkcheck2] +optional = true \ No newline at end of file diff --git a/measuring/use_gqm.md b/measuring/use_gqm.md index f30208d..525a88e 100644 --- a/measuring/use_gqm.md +++ b/measuring/use_gqm.md @@ -31,32 +31,47 @@ graph LR; subgraph GQM[Goals, Questions, Metrics] %% begin nodes find-projects.md[Find InnerSource Projects] + index.md[InnerSource Goals] reduce-duplication.md[Reduce duplication] adoption-trend.md[What is the InnerSource adoption trend?] + index.md[InnerSource Questions] who-contributes.md[Who contributes to the InnerSource project?] who-uses.md[Who uses the InnerSource project?] code-contributions.md[Code contributions] contribution-distance.md[Contribution Distance] + index.md[InnerSource Metrics] number-of-innersource-repositories.md[Number of InnerSource repositories] usage-count.md[Usage count] %% begin edges find-projects.md-->who-uses.md find-projects.md-->who-contributes.md + index.md-->find-projects.md + index.md-->reduce-duplication.md reduce-duplication.md-->who-uses.md adoption-trend.md-->number-of-innersource-repositories.md + index.md-->adoption-trend.md + index.md-->who-contributes.md + index.md-->who-uses.md who-contributes.md-->code-contributions.md who-contributes.md-->contribution-distance.md who-uses.md-->usage-count.md + index.md-->code-contributions.md + index.md-->contribution-distance.md + index.md-->number-of-innersource-repositories.md + index.md-->usage-count.md %% begin clicks - click find-projects.md "/measuring/goals/find-projects" "Find InnerSource Projects" - click reduce-duplication.md "/measuring/goals/reduce-duplication" "Reduce duplication" - click adoption-trend.md "/measuring/questions/adoption-trend" "What is the InnerSource adoption trend?" - click who-contributes.md "/measuring/questions/who-contributes" "Who contributes to the InnerSource project?" - click who-uses.md "/measuring/questions/who-uses" "Who uses the InnerSource project?" - click code-contributions.md "/measuring/metrics/code-contributions" "Code contributions" - click contribution-distance.md "/measuring/metrics/contribution-distance" "Contribution Distance" - click number-of-innersource-repositories.md "/measuring/metrics/number-of-innersource-repositories" "Number of InnerSource repositories" - click usage-count.md "/measuring/metrics/usage-count" "Usage count" + click find-projects.md "goals/find-projects.html" "Find InnerSource Projects" + click index.md "goals/index.html" "InnerSource Goals" + click reduce-duplication.md "goals/reduce-duplication.html" "Reduce duplication" + click adoption-trend.md "questions/adoption-trend.html" "What is the InnerSource adoption trend?" + click index.md "questions/index.html" "InnerSource Questions" + click who-contributes.md "questions/who-contributes.html" "Who contributes to the InnerSource project?" + click who-uses.md "questions/who-uses.html" "Who uses the InnerSource project?" + click code-contributions.md "metrics/code-contributions.html" "Code contributions" + click contribution-distance.md "metrics/contribution-distance.html" "Contribution Distance" + click index.md "metrics/index.html" "InnerSource Metrics" + click number-of-innersource-repositories.md "metrics/number-of-innersource-repositories.html" "Number of InnerSource repositories" + click usage-count.md "metrics/usage-count.html" "Usage count" end subgraph Legend direction TB @@ -65,13 +80,13 @@ graph LR; metric[Metric] classDef goals stroke:green,stroke-width:2px; - class goal,find-projects.md,reduce-duplication.md goals + class goal,find-projects.md,index.md,reduce-duplication.md goals classDef questions stroke:orange,stroke-width:2px; - class question,adoption-trend.md,who-contributes.md,who-uses.md questions + class question,adoption-trend.md,index.md,who-contributes.md,who-uses.md questions classDef metrics stroke:purple,stroke-width:2px; - class metric,code-contributions.md,contribution-distance.md,number-of-innersource-repositories.md,usage-count.md metrics + class metric,code-contributions.md,contribution-distance.md,index.md,number-of-innersource-repositories.md,usage-count.md metrics end ``` diff --git a/scripts/build.sh b/scripts/build.sh new file mode 100755 index 0000000..bf13776 --- /dev/null +++ b/scripts/build.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# Build the book locally. +# Usage: ./scripts/build.sh +# +# On first run this will install Rust, mdBook, and its plugins into the +# repo-local .cargo/ and .rustup/ directories (ignored by git). Subsequent +# runs reuse the existing install. +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" + +# Point Rust/Cargo at repo-local directories (matches CI and install-mdbook.sh) +export RUSTUP_HOME="${REPO_ROOT}/.rustup" +export CARGO_HOME="${REPO_ROOT}/.cargo" +export PATH="${CARGO_HOME}/bin:${PATH}" + +# Install mdBook if it isn't already present +if [ ! -x "${CARGO_HOME}/bin/mdbook" ]; then + echo "mdBook not found — running first-time install (this may take a few minutes)…" + bash "${REPO_ROOT}/scripts/install-mdbook.sh" +fi + +cd "${REPO_ROOT}" +mdbook build "$@" diff --git a/scripts/gqm_gen/index.test.ts b/scripts/gqm_gen/index.test.ts index 9208024..0ae9b34 100644 --- a/scripts/gqm_gen/index.test.ts +++ b/scripts/gqm_gen/index.test.ts @@ -7,9 +7,17 @@ import { getLinks, getFileLinks, generateMermaidDiagram, - getGQMFileLinks + getGQMFileLinks, + getLinkUrl, } from "./index"; +test("getLinkUrl targets built HTML pages", () => { + assert.strictEqual( + getLinkUrl(LinkType.GOAL, "find-projects.md"), + "goals/find-projects.html" + ); +}); + test("can get links", () => { const node = new Commonmark.Node("paragraph"); const links = getLinks(node); @@ -38,3 +46,11 @@ test("can generate mermaid diagram from file", () => { const diagram = generateMermaidDiagram(graph); assert(diagram.indexOf("graph LR;") > 1); }); + +test("GQM graph excludes template markdown from link edges", () => { + const graph = getGQMFileLinks("../../measuring/"); + const hasTemplateEdge = graph.edges.some( + (e) => e.to?.endsWith("template.md") ?? false + ); + assert.strictEqual(hasTemplateEdge, false); +}); diff --git a/scripts/gqm_gen/index.ts b/scripts/gqm_gen/index.ts index 6bf4a97..d573d35 100644 --- a/scripts/gqm_gen/index.ts +++ b/scripts/gqm_gen/index.ts @@ -10,9 +10,8 @@ const outputPath = process.env.npm_config_outputPath || "../../measuring/use_gqm const graph = getGQMFileLinks(mdFilePath); export function getLinkUrl(linkType: LinkType, file: string) { - const measuringUrl = "/measuring"; - const url = `${measuringUrl}/${linkType.toLowerCase()}s/${file}` - return url; + const htmlFile = file.replace(/\.md$/i, ".html"); + return `${linkType.toLowerCase()}s/${htmlFile}`; } export function getGQMFileLinks(mdFilePath: string): Graph { @@ -82,11 +81,17 @@ export function getLinks(parsed: Commonmark.Node): Link[] { node = event.node; if (event.entering && node.type === "link") { const destination = node.destination as string; - if (destination.includes('.md') && !destination.includes('use_gqm')) { + const linkFileName = path.parse(destination).base; + // Match getFileLinks readdir filter: skip template stubs linked from index pages. + if ( + destination.includes('.md') && + !destination.includes('use_gqm') && + !linkFileName.endsWith('template.md') + ) { links.push({ url: destination, text: node.firstChild?.literal as string, - name: path.parse(destination).base + name: linkFileName }); } } @@ -105,12 +110,8 @@ function getNodeShapeSyntax(node: Node): string { } export function generateMermaidDiagram(graph: Graph): string { - console.log('graph', graph); - const { nodes, edges } = graph; - const getLinkUrl = (type: LinkType, nodeId: string) => `/measuring/${type.toLowerCase()}s/${nodeId}`; - let mermaidSyntax = "```mermaid\ngraph LR;\n subgraph GQM[Goals, Questions, Metrics]\n"; // Add nodes @@ -128,7 +129,7 @@ export function generateMermaidDiagram(graph: Graph): string { // Add click handlers mermaidSyntax += " %% begin clicks\n"; nodes.forEach(node => { - const url = getLinkUrl(node.type, node.id).replace('.md', ''); + const url = getLinkUrl(node.type, node.id); mermaidSyntax += ` click ${node.id} "${url}" "${node.label}"\n`; }); @@ -157,25 +158,33 @@ export function updateGQMDiagram(): void { const graph = getGQMFileLinks(mdFilePath); const mermaidContent = generateMermaidDiagram(graph); - + + // Strip the markdown fences to get raw mermaid syntax + const rawMermaid = mermaidContent + .replace(/^```mermaid\n/, '') + .replace(/\n```$/, ''); + + // Write raw mermaid to stdout so it can be piped to mmdc + process.stdout.write(rawMermaid + '\n'); + // Check if the output file exists if (!fs.existsSync(outputPath)) { console.error(`Error: Output file not found at ${outputPath}`); process.exit(1); } - + // Read the existing file const existingContent = fs.readFileSync(outputPath, 'utf-8'); - + // Replace the mermaid block const updatedContent = existingContent.replace( /```mermaid[\s\S]*?```/, mermaidContent ); - + // Write back to file fs.writeFileSync(outputPath, updatedContent); - console.log(`Successfully updated GQM diagram at ${outputPath}`); + console.error(`Successfully updated GQM diagram at ${outputPath}`); } catch (error) { console.error('Error updating GQM diagram:', error); process.exit(1); diff --git a/scripts/install-mdbook.sh b/scripts/install-mdbook.sh index 5aefa99..b7454b5 100755 --- a/scripts/install-mdbook.sh +++ b/scripts/install-mdbook.sh @@ -16,10 +16,11 @@ export CARGO_HOME="${REPO_ROOT}/.cargo" echo "Installing Rust and mdBook into ${REPO_ROOT} (RUSTUP_HOME=$RUSTUP_HOME, CARGO_HOME=$CARGO_HOME)" -if ! command -v rustup >/dev/null 2>&1; then +# Install Rust into repo-local RUSTUP_HOME/CARGO_HOME if not already there +if [ ! -x "${CARGO_HOME}/bin/rustup" ]; then curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --no-modify-path - source "${CARGO_HOME}/env" fi +source "${CARGO_HOME}/env" rustup toolchain install "${RUST_TOOLCHAIN_VERSION}" --profile minimal rustup default "${RUST_TOOLCHAIN_VERSION}" diff --git a/scripts/serve.sh b/scripts/serve.sh new file mode 100755 index 0000000..07913e8 --- /dev/null +++ b/scripts/serve.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# Build and serve the book locally with live-reload. +# Usage: ./scripts/serve.sh +# ./scripts/serve.sh --open # also opens a browser tab +# +# On first run this will install Rust, mdBook, and its plugins into the +# repo-local .cargo/ and .rustup/ directories (ignored by git). Subsequent +# runs reuse the existing install. +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" + +# Point Rust/Cargo at repo-local directories (matches CI and install-mdbook.sh) +export RUSTUP_HOME="${REPO_ROOT}/.rustup" +export CARGO_HOME="${REPO_ROOT}/.cargo" +export PATH="${CARGO_HOME}/bin:${PATH}" + +# Install mdBook if it isn't already present +if [ ! -x "${CARGO_HOME}/bin/mdbook" ]; then + echo "mdBook not found — running first-time install (this may take a few minutes)…" + bash "${REPO_ROOT}/scripts/install-mdbook.sh" +fi + +cd "${REPO_ROOT}" +mdbook serve "$@"