Merge pull request #107 from InnerSourceCommons/add-ai-section

jeffabailey · web-flow · commit 6685f5bf6656 · 2026-03-18T05:31:23.000-07:00
feat: add InnerSource and AI section
diff --git a/.github/act/pull_request.json b/.github/act/pull_request.json
@@ -0,0 +1,18 @@
+{
+  "act": true,
+  "action": "synchronize",
+  "repository": {
+    "fork": false,
+    "default_branch": "main",
+    "name": "managing-innersource-projects",
+    "full_name": "InnerSourceCommons/managing-innersource-projects"
+  },
+  "pull_request": {
+    "number": 107,
+    "head": {
+      "repo": {
+        "full_name": "InnerSourceCommons/managing-innersource-projects"
+      }
+    }
+  }
+}
diff --git a/.github/act/push.json b/.github/act/push.json
@@ -0,0 +1,7 @@
+{
+  "act": true,
+  "repository": {
+    "fork": false,
+    "default_branch": "main"
+  }
+}
diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
@@ -1,28 +1,33 @@
 # Workflow for building and deploying a mdBook site to GitHub Pages.
-# Serves the main book at / and PR previews at /pr-<number>/ by merging
-# pr-* directories from the gh-pages branch (pushed by mdbook-pr-preview.yml)
-# into the deployed artifact. Works with Pages source "GitHub Actions".
+# - On push to main: deploys to the root of gh-pages.
+# - On pull_request: deploys a preview under pr-preview/pr-<number>/ on gh-pages,
+#   comments the preview URL, and cleans up when the PR closes.
+#
+# Repo Settings required:
+#   Pages -> Source: "Deploy from a branch" -> gh-pages / (root)
+#   Actions -> General -> Workflow permissions: "Read and write permissions"
 #
 # See: https://rust-lang.github.io/mdBook/index.html
 name: Deploy mdBook site to Pages
 
 on:
   push:
     branches: ["main"]
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
   workflow_dispatch:
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
+  contents: write
+  pull-requests: write
 
 jobs:
-  build:
+  deploy:
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     env:
       CARGO_HOME: ${{ github.workspace }}/.cargo
       RUSTUP_HOME: ${{ github.workspace }}/.rustup
@@ -71,40 +76,73 @@ jobs:
       - name: Build with mdBook
         run: ${{ env.CARGO_HOME }}/bin/mdbook build
 
-      - name: Merge PR previews from gh-pages into artifact
-        run: |
-          set -e
-          echo "Fetching gh-pages branch..."
-          git fetch origin gh-pages 2>/dev/null || true
-          if ! git rev-parse -q origin/gh-pages >/dev/null 2>&1; then
-            echo "No gh-pages branch found; skipping PR preview merge."
-            exit 0
-          fi
-          PR_DIRS=$(git ls-tree -d --name-only origin/gh-pages 2>/dev/null | grep -E '^pr-[0-9]+$' || true)
-          if [ -z "$PR_DIRS" ]; then
-            echo "No pr-* directories on gh-pages; skipping."
-            exit 0
-          fi
-          echo "Merging PR preview dirs: $PR_DIRS"
-          for d in $PR_DIRS; do
-            echo "  -> merging $d"
-            git archive origin/gh-pages "$d" | tar -x -C book
-          done
-          echo "Done. Contents of book/ after merge:"
-          ls -la book/ | head -30
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
         with:
-          path: ./book
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book
+          keep_files: true
 
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  preview:
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
-    needs: build
+    concurrency: preview-${{ github.ref }}
+    env:
+      CARGO_HOME: ${{ github.workspace }}/.cargo
+      RUSTUP_HOME: ${{ github.workspace }}/.rustup
     steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+      - uses: actions/checkout@v4
+
+      - name: Cache Cargo registry and git index
+        if: github.event.action != 'closed'
+        uses: actions/cache@v4
+        with:
+          path: |
+            ${{ env.CARGO_HOME }}/registry
+            ${{ env.CARGO_HOME }}/git
+          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('scripts/install-mdbook.sh') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-registry-
+
+      - name: Cache Rust toolchains
+        if: github.event.action != 'closed'
+        uses: actions/cache@v4
+        with:
+          path: |
+            ${{ env.RUSTUP_HOME }}/toolchains
+            ${{ env.RUSTUP_HOME }}/update-hashes
+          key: ${{ runner.os }}-rust-toolchain-${{ hashFiles('scripts/install-mdbook.sh') }}
+          restore-keys: |
+            ${{ runner.os }}-rust-toolchain-
+
+      - name: Cache installed mdBook binaries
+        if: github.event.action != 'closed'
+        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-
+
+      - name: Install mdBook
+        if: github.event.action != 'closed' && steps.mdbook-cache.outputs.cache-hit != 'true'
+        run: bash scripts/install-mdbook.sh
+        env:
+          REPO_ROOT: ${{ github.workspace }}
+
+      - name: Add Cargo bin to PATH
+        if: github.event.action != 'closed'
+        run: echo "${CARGO_HOME}/bin" >> "$GITHUB_PATH"
+
+      - name: Build with mdBook
+        if: github.event.action != 'closed'
+        run: ${{ env.CARGO_HOME }}/bin/mdbook build
+
+      - name: Deploy PR preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./book
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
diff --git a/MDBOOK.md b/MDBOOK.md
@@ -20,15 +20,10 @@ cargo install mdbook --version 0.4.52
 Install required preprocessors:
 
 ```sh
-# Install mdbook-mermaid v0.10.0 (compatible with mdbook 0.4.52)
-cargo install mdbook-mermaid --version 0.10.0
-
-# Install mdbook-embedify for embedding external content
+cargo install mdbook-mermaid
 cargo install mdbook-embedify
 ```
 
-**Note:** These specific versions are required for compatibility. mdbook-embedify 0.2.18 is not compatible with mdbook 0.5.x, so we use mdbook 0.4.52 and a compatible version of mdbook-mermaid.
-
 ## Usage
 
 To build the book, run the following command:
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -31,6 +31,11 @@
   * [References](measuring/references.md)
   * [Authors and Reviewers](measuring/authors.md)
 * [Governance](governance/governance.md)
+* [InnerSource and AI](innersource-and-ai/innersource-and-ai.md)
+  * [Why InnerSource Matters When Adopting AI](innersource-and-ai/why-innersource-matters-with-ai.md)
+  * [Shaping Repositories and Practices for AI](innersource-and-ai/shaping-for-ai.md)
+  * [Risks and Guardrails](innersource-and-ai/risks-and-guardrails.md)
+  * [Authors and Reviewers](innersource-and-ai/authors.md)
 * [Tooling](tooling/innersource-tooling.md)
   * [GitHub Strategy](tooling/github-strategy.md)
   * [GitHub Configuration](tooling/github-configuration.md)
diff --git a/book.toml b/book.toml
@@ -20,4 +20,6 @@ giscus.loading = "lazy"
 giscus.crossorigin = "anonymous"
 
 [output.html]
+# 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"]
diff --git a/governance/governance.md b/governance/governance.md
@@ -250,6 +250,8 @@ 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).
+
 [^1]: http://oss-watch.ac.uk/resources/governancemodels
 
 [^2]: https://ospo-alliance.org/ggi/
diff --git a/innersource-and-ai/authors.md b/innersource-and-ai/authors.md
@@ -0,0 +1,17 @@
+# Authors and Reviewers
+
+## Authors
+
+Chronological order:
+
+* InnerSource Program Office (ISPO) Working Group, [InnerSource Commons](https://innersourcecommons.org/).
+
+## Reviewers
+
+Chronological order:
+
+* Jeff Bailey
+* Russ Rutledge
+* Micaela Eller
+
+This section was drafted as a discussion starter and is open for contributions. If you would like to be listed as an author or reviewer, please open a pull request or get in touch via [Slack](https://innersourcecommons.org/slack).
diff --git a/innersource-and-ai/innersource-and-ai.md b/innersource-and-ai/innersource-and-ai.md
@@ -0,0 +1,13 @@
+# 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.
+
+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.
+
+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
@@ -0,0 +1,9 @@
+# Risks and Guardrails
+
+AI is the ultimate InnerSource contributor. Like any external contributor, AI agents generate code that must be reviewed, validated, and integrated thoughtfully into your systems. The same InnerSource practices that enable trusted external contributions—code review, clear guidelines, transparent decision-making, and systems thinking—are exactly what you need to safely and sustainably adopt AI in development.
+
+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.
+
+## 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
@@ -0,0 +1,21 @@
+# Shaping Repositories and Practices for AI
+
+InnerSource practices that make life easier for human contributors also help AI systems and agentic tools. Clear scope, good documentation, and consistent workflows make it easier for both people and AI to discover, understand, and contribute to shared code safely.
+
+## Repository and boundary design
+
+Well-defined repositories with clear scope and interfaces make it easier for humans and AI to contribute without stepping on each other’s toes. When boundaries are explicit—what belongs in this repo, what the APIs are, what the project is *not* responsible for—AI agents and assistants can operate within a manageable context. The community is exploring a pattern sometimes called “InnerSource the AI way,” which emphasizes clear scope and boundaries; as it matures, it may be documented in the [InnerSource Patterns](https://patterns.innersourcecommons.org/) book and linked from here.
+
+## Documentation and discoverability
+
+InnerSource behaviors like solid READMEs, CONTRIBUTING guides, and architecture decision records are increasingly important when AI is in the loop. They help AI and people alike understand how to use and extend shared code correctly. Documentation that explains *why* decisions were made, not just *what* the code does, supports better AI-generated contributions and reduces misuse. Making repositories searchable and well-described also helps teams and tools find the right building blocks instead of reimplementing them.
+
+## Playbooks for people and agents
+
+Playbooks that describe how to contribute—and what to avoid—benefit both human contributors and AI-assisted workflows. The community is starting to develop playbooks that work for both. As these emerge, they will be reflected in the InnerSource Patterns book and linked from this section. The goal is to make it easy for contributors and tools to follow the same rules and expectations.
+
+## Skills, plugins, and workflow integration
+
+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.
+
+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
@@ -0,0 +1,27 @@
+# Why InnerSource Matters When Adopting AI
+
+AI and agentic coding are changing how development work gets done. Developers spend more time specifying requirements and guiding AI tools than writing every line of code by hand. Yet collaboration, reuse, and clear boundaries remain critical. InnerSource helps organizations move faster with *shared* components and practices instead of scattered, duplicated solutions.
+
+## InnerSource is more relevant than ever
+
+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.
+
+## 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).
+
+## 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.
+
+## Platforms ready for InnerSource
+
+Platforms and tooling play a crucial role in enabling InnerSource at scale. As organizations adopt AI and agentic workflows, collaboration platforms must support discovery, visibility, and contribution across team boundaries. Platforms that make it easy to find reusable components, understand interfaces, and submit improvements reduce friction and encourage participation. Investment in platform capabilities—search, documentation, governance workflows, and integration with development tools—directly multiplies the effectiveness of InnerSource practices in an AI-augmented environment.
+
+## Enterprise AI and production readiness
+
+This section focuses on large-scale enterprise adoption of AI—internal tools, pipelines, and agentic workflows—rather than consumer-facing AI products. In that context, the difference between prototype AI solutions and production-ready ones matters a lot. InnerSource practices—transparency, code review, documentation, and governance—help teams build robust, secure, and maintainable AI-assisted development. They also help leaders see what is ready for production and what still needs work.
+
+## Evidence and further reading
+
+AI tooling and organizational practices are evolving. This section will be updated with results from the [InnerSource Commons](https://innersourcecommons.org/) survey and from research partnerships (e.g. with universities, [FINOS](https://finos.org/), and other organizations) as data becomes available. If you have case studies or data to share, we encourage you to contribute or get in touch via the [InnerSource Commons Slack](https://innersourcecommons.org/slack).
diff --git a/introduction/framework.md b/introduction/framework.md
@@ -112,3 +112,7 @@ Open measurement gives a lot of benefits for our InnerSource community:
 
 - transparency, as trust generator for third parties and fairness
   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.
diff --git a/mdbook b/mdbook
diff --git a/scripts/install-mdbook.sh b/scripts/install-mdbook.sh
diff --git a/scripts/test-mdbook-deploy.sh b/scripts/test-mdbook-deploy.sh
diff --git a/tooling/innersource-tooling.md b/tooling/innersource-tooling.md
