Merge pull request #111 from InnerSourceCommons/enhance-innersource-ai

Expand InnerSource and AI section with agentic coding topics

Author: jeffabailey

.github/workflows/mdbook.yml

@@ -44,28 +44,26 @@ 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
         with:
           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 }}

.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

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/).
@@ -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,15 +33,12 @@ 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
-[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

Makefile

@@ -0,0 +1,7 @@
+.PHONY: build serve
+
+build:
+	./scripts/build.sh
+
+serve:
+	./scripts/serve.sh

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?
 
@@ -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
@@ -40,9 +64,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 +84,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](./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

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)

book.toml

@@ -23,3 +23,6 @@ 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]
+optional = true

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
 

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,

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.
+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.