Generate mind map automatically (via GHA)

.github/workflows/generate-mindmap.yml

@@ -0,0 +1,45 @@
+name: Generate Mindmap
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    paths:
+      - ".github/workflows/generate-mindmap.yml"
+      - "pattern-categorization/innersource-program-mind-map.md"
+
+defaults:
+  run:
+    working-directory: pattern-categorization
+
+jobs:
+  generate-mindmap:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js
+      uses: actions/setup-node@v2
+      with:
+        node-version: 12.x
+        cache: 'npm'
+        cache-dependency-path: pattern-categorization/package-lock.json
+    - name: Install Node.js dependencies
+      run: npm install
+    - name: Run Markmap
+      run: npx markmap --no-toolbar innersource-program-mind-map.md -o innersource-program-mind-map.html
+    - name: Screenshot Markmap Website
+      id: screenshot-generator
+      uses: swinton/screenshot-website@v1.x
+      with:
+        source: pattern-categorization/innersource-program-mind-map.html
+        destination: innersource-program-mind-map.png
+        full-page: false
+    - name: Copy Screenshot
+      run: cp ${{ steps.screenshot-generator.outputs.path }} .
+    - name: Reduce Screenshot Size (PNG)
+      run: npx optipng innersource-program-mind-map.png
+    - name: Commit Changes
+      uses: stefanzweifel/git-auto-commit-action@v4
+      with:
+        commit_message: Re-creating markmap and screenshot

book/README.md

@@ -22,6 +22,7 @@ The `./book` folder contains generator scripts and some extra content required t
 - `.github/workflows/book.yml` - A GitHub Action that triggers the execution of `/book/generate_toc.rb`.
 - `/book/introduction.md` - The introduction to our book. This content is what the reader sees first when they open the book. The current content is based on [README.md](../README.md). We may need to modify this content even further, to address the readers of the book more specifically, rather than the readers of our GitHub repository.
 - `/book/contribute.md` - Information about how to contribute to this book.
+- `/book/explore-patterns.md` - Dedicated page in the book that highlights the mind map of all patterns.
 
 ## Objectives of the book
 

book/explore-patterns.md

@@ -6,7 +6,7 @@ Now how to make it easy for readers to discover the patterns that can help them
 
 For this purpose we provide this mind map. It **categorizes patterns based on the different phases of an InnerSource Program**, and the challenges that might appear in the respective phases.
 
-<img src="./innersource-program-mind-map.png" title="InnerSource Patterns as a Mind Map">
+<img src="../pattern-categorization/innersource-program-mind-map.png" title="InnerSource Patterns as a Mind Map">
 
 ## Improve this Mind Map
 

book/toc_template.md

@@ -14,7 +14,7 @@ Instead edit toc_template.md
 * [Explore Patterns](../book/explore-patterns.md)
 * [Contribute to this book](../book/contribute.md)
 
-<img src="./innersource-program-mind-map.png" title="InnerSource Patterns as a Mind Map">
+<img src="../pattern-categorization/innersource-program-mind-map.png" title="InnerSource Patterns as a Mind Map">
 
 ## Patterns <a id="p"></a>
 

pattern-categorization/.gitignore

@@ -0,0 +1 @@
+node_modules/

pattern-categorization/README.md

@@ -6,34 +6,38 @@ Now how do we make it easier for readers to discover the patterns that can help
 
 ## InnerSource Program Mind Map
 
-This first categorization effort uses a mind map to categorize patterns based on the different phases of an InnerSource Program, and the challenges that might appear in the respective phases. See [innersource-program-mind-map.html](innersource-program-mind-map.html). Note that this is still an incomplete visualization i.e. it does not contain all of our patterns.
+This first categorization effort uses a mind map to categorize patterns based on the different phases of an InnerSource Program, and the challenges that might appear in the respective phases. See [innersource-program-mind-map.html](innersource-program-mind-map.html). Note that this mind map contains only the patterns that are published in our book (i.e. Level 2-Structured and higher).
 
 In the mind map you will see patterns categorized from left to right in increasing levels of detail.
 
-The logic for these levels is:
+The logic for these levels is (from left to right):
 
 - level 0: the InnerSource program itself (as the root)
 - level 1: phase of an InnerSource Program
 - level 2: problem category
 - level 3: specific problem occurring in an InnerSource context
 - level 4: pattern (solution to the problem)
 
-To add new patterns to the mind map, edit the source file `innersource-program-mind-map.md`, and then regenerate the visualization like this:
+## Adding a Pattern to the Mind Map
+
+To add new patterns to the mind map, edit the file [innersource-program-mind-map.md](innersource-program-mind-map.md). Also see the explanation of the different levels in the mind map above.
+
+Then create a PR with your changes. This triggers an [action](https://github.com/InnerSourceCommons/InnerSourcePatterns/actions/workflows/generate-mindmap.yml) that generates the mind map in HTML and PNG format, and adds those to your PR.
+
+To test your changes locally, you can also generate the mind map yourself like this:
 
 ```
-npm install markmap-lib -g
+npm install -g markmap-cli
 markmap innersource-program-mind-map.md
 ```
 
-Once this is done please replace `book/innersource-program-mind-map.jpg` with an updated version of this mind map.
-
 ## Future Ideas for Categorization
 
 We have some other ideas for categories by which the InnerSource Patterns could be grouped.
 
-One is **management and empowerment**. Some patterns help to manage, govern, mitigate risk. Some other patterns help to empower, attract, build communities. This categorization can help others to quickly find the group of patterns that fit their needs.
-
-Another angle is **single project vs organization**. Some patterns are applicable to single project, while others are organizational effort. For people working on specific initiative, single project level patterns might be more interesting. For people working on scaling InnerSource, organizational patterns are important.
+* **Single Project vs Organization** - Some patterns are applicable to single project, while others are organizational effort. For people working on specific initiative, single project level patterns might be more interesting. For people working on scaling InnerSource, organizational patterns are important.
+* **InnerSource Adoption Obstacles** - The [2020 State of InnerSource Research](https://innersourcecommons.org/documents/surveys/State.of.InnerSource.Report.2020.pdf) identifies various obstacles for InnerSource adoption (see page 25). We could identify the patterns that help address each of these obstacles.
+* **Management and Empowerment** - Some patterns help to manage, govern, mitigate risk. Some other patterns help to empower, attract, build communities. This categorization can help others to quickly find the group of patterns that fit their needs.
 
 ## References
 

pattern-categorization/innersource-program-mind-map.html

@@ -20,12 +20,11 @@
 </head>
 <body>
 <svg id="mindmap"></svg>
-<script src="https://cdn.jsdelivr.net/npm/d3@5"></script><script src="https://cdn.jsdelivr.net/npm/markmap-lib@0.7.6/dist/browser/view.min.js"></script><script>((data, ...processors) => {
+<script src="https://cdn.jsdelivr.net/npm/d3@6.6.0"></script><script src="https://cdn.jsdelivr.net/npm/markmap-view@0.2.6"></script><script>((getMarkmap, getOptions, data) => {
         const {
           Markmap
-        } = window.markmap;
-        Markmap.processors = processors;
-        Markmap.create('svg#mindmap', null, data);
-      })({"t":"heading","d":1,"v":"<a href=\"https://patterns.innersourcecommons.org/toc\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">InnerSource Program</a>","c":[{"t":"heading","d":2,"v":"Begin","c":[{"t":"heading","d":3,"v":"Program Setup","c":[{"t":"heading","d":4,"v":"Management hesitates to invest in InnerSource","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/start-as-experiment\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Start as an Experiment</a>"}]},{"t":"heading","d":4,"v":"Slow community growth hinders InnerSource","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/dedicated-community-leader\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Dedicated Community Leader</a>"}]}]},{"t":"heading","d":3,"v":"Project Setup","c":[{"t":"heading","d":4,"v":"Hard to assess a project quickly","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/base-documentation\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Standard Base Documentation</a>"}]},{"t":"heading","d":4,"v":"Ad-hoc communication hinders project growth","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/communication-tooling\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Communication Tooling</a>"}]},{"t":"heading","d":4,"v":"Intransparent roadmap and direction of the project","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/issue-tracker\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Issue Tracker Use Cases</a>"}]}]}]},{"t":"heading","d":2,"v":"Adoption","c":[{"t":"heading","d":3,"v":"Valuation Challenges","c":[{"t":"heading","d":4,"v":"How to measure a project's business value","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/crossteam-project-valuation\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Cross-Team Project Valuation</a>"}]}]},{"t":"heading","d":3,"v":"Cultural Challenges","c":[{"t":"heading","d":4,"v":"Unrecognized effort","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/praise-participants\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Praise Participants</a>"},{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/trusted-committer\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Trusted Committer</a>"}]}]},{"t":"heading","d":3,"v":"Technical Challenges","c":[{"t":"heading","d":4,"v":"Not meeting everyone's needs","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/common-requirements\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Common Requirements</a>"}]},{"t":"heading","d":4,"v":"Fear of shared support responsibility","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/service-vs-library\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Service vs. Library</a>"}]}]},{"t":"heading","d":3,"v":"Organizational Challenges","c":[{"t":"heading","d":4,"v":"Discouragement of contributing resource","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/contracted-contributor\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Contracted Contributor</a>"}]},{"t":"heading","d":4,"v":"Rejection of accepting contribution","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/30-day-warranty\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">30 Day Warranty</a>"}]},{"t":"heading","d":4,"v":"Radical change of management","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/review-committee\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Review Committee</a>"}]},{"t":"heading","d":4,"v":"Fear of shared support responsibility","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/service-vs-library\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Service vs. Library</a>"}]},{"t":"heading","d":4,"v":"Not enough maintainers to scale","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/trusted-committer\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Trusted Committer</a>"}]},{"t":"heading","d":4,"v":"Difficult cross-team coordination","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/transparent-cross-team-decision-making-using-rfcs\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Transparent Cross-Team Decision Making using RFCs</a>"}]}]},{"t":"heading","d":3,"v":"Cross Legal Entities Challenges","c":[{"t":"heading","d":4,"v":"Concern on legal liabilities or cross-company accounting","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/innersource-license\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">InnerSource License</a>"}]}]}]},{"t":"heading","d":2,"v":"Grow","c":[{"t":"heading","d":3,"v":"Discovery Challenges","c":[{"t":"heading","d":4,"v":"Can't find matching projects","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/gig-marketplace\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Gig Marketplace</a>"},{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/innersource-portal\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">InnerSource Portal</a>"}]},{"t":"heading","d":4,"v":"Difficult to find active projects","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/repository-activity-score\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Repository Activity Score</a>"}]}]}]},{"t":"heading","d":2,"v":"Scale","c":[{"t":"heading","d":3,"v":"Self Education/Improvement Challenges","c":[{"t":"heading","d":4,"v":"Not aware of InnerSource best practices","c":[{"t":"heading","d":5,"v":"<a href=\"https://patterns.innersourcecommons.org/p/maturity-model\" title=\"\" target=\"_blank\" rel=\"noopener noreferrer\">Maturity Model</a>"}]}]}]}]})</script>
+        } = getMarkmap();
+        window.mm = Markmap.create('svg#mindmap', getOptions == null ? void 0 : getOptions(), data);
+      })(() => window.markmap,null,{"t":"heading","d":1,"p":{"lines":[0,1]},"v":"<a href=\"https://patterns.innersourcecommons.org/toc\">InnerSource Program</a>","c":[{"t":"heading","d":2,"p":{"lines":[2,3]},"v":"Begin","c":[{"t":"heading","d":3,"p":{"lines":[4,5]},"v":"Program Setup","c":[{"t":"heading","d":4,"p":{"lines":[6,7]},"v":"Management hesitates to invest in InnerSource","c":[{"t":"heading","d":5,"p":{"lines":[8,9]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/start-as-experiment\">Start as an Experiment</a>"}]},{"t":"heading","d":4,"p":{"lines":[10,11]},"v":"Slow community growth hinders InnerSource","c":[{"t":"heading","d":5,"p":{"lines":[12,13]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/dedicated-community-leader\">Dedicated Community Leader</a>"}]}]},{"t":"heading","d":3,"p":{"lines":[14,15]},"v":"Project Setup","c":[{"t":"heading","d":4,"p":{"lines":[16,17]},"v":"Hard to assess a project quickly","c":[{"t":"heading","d":5,"p":{"lines":[18,19]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/base-documentation\">Standard Base Documentation</a>"}]},{"t":"heading","d":4,"p":{"lines":[20,21]},"v":"Ad-hoc communication hinders project growth","c":[{"t":"heading","d":5,"p":{"lines":[22,23]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/communication-tooling\">Communication Tooling</a>"}]},{"t":"heading","d":4,"p":{"lines":[24,25]},"v":"Intransparent roadmap and direction of the project","c":[{"t":"heading","d":5,"p":{"lines":[26,27]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/issue-tracker\">Issue Tracker Use Cases</a>"}]}]}]},{"t":"heading","d":2,"p":{"lines":[28,29]},"v":"Adoption","c":[{"t":"heading","d":3,"p":{"lines":[30,31]},"v":"Valuation Challenges","c":[{"t":"heading","d":4,"p":{"lines":[32,33]},"v":"How to measure a project's business value","c":[{"t":"heading","d":5,"p":{"lines":[34,35]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/crossteam-project-valuation\">Cross-Team Project Valuation</a>"}]}]},{"t":"heading","d":3,"p":{"lines":[36,37]},"v":"Cultural Challenges","c":[{"t":"heading","d":4,"p":{"lines":[38,39]},"v":"Unrecognized effort","c":[{"t":"heading","d":5,"p":{"lines":[40,41]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/praise-participants\">Praise Participants</a>"},{"t":"heading","d":5,"p":{"lines":[42,43]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/trusted-committer\">Trusted Committer</a>"}]}]},{"t":"heading","d":3,"p":{"lines":[44,45]},"v":"Technical Challenges","c":[{"t":"heading","d":4,"p":{"lines":[46,47]},"v":"Not meeting everyone's needs","c":[{"t":"heading","d":5,"p":{"lines":[48,49]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/common-requirements\">Common Requirements</a>"}]},{"t":"heading","d":4,"p":{"lines":[50,51]},"v":"Fear of shared support responsibility","c":[{"t":"heading","d":5,"p":{"lines":[52,53]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/service-vs-library\">Service vs. Library</a>"}]}]},{"t":"heading","d":3,"p":{"lines":[54,55]},"v":"Organizational Challenges","c":[{"t":"heading","d":4,"p":{"lines":[56,57]},"v":"Discouragement of contributing resource","c":[{"t":"heading","d":5,"p":{"lines":[58,59]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/contracted-contributor\">Contracted Contributor</a>"}]},{"t":"heading","d":4,"p":{"lines":[60,61]},"v":"Rejection of accepting contribution","c":[{"t":"heading","d":5,"p":{"lines":[62,63]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/30-day-warranty\">30 Day Warranty</a>"}]},{"t":"heading","d":4,"p":{"lines":[64,65]},"v":"Radical change of management","c":[{"t":"heading","d":5,"p":{"lines":[66,67]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/review-committee\">Review Committee</a>"}]},{"t":"heading","d":4,"p":{"lines":[68,69]},"v":"Fear of shared support responsibility","c":[{"t":"heading","d":5,"p":{"lines":[70,71]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/service-vs-library\">Service vs. Library</a>"}]},{"t":"heading","d":4,"p":{"lines":[72,73]},"v":"Not enough maintainers to scale","c":[{"t":"heading","d":5,"p":{"lines":[74,75]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/trusted-committer\">Trusted Committer</a>"}]},{"t":"heading","d":4,"p":{"lines":[76,77]},"v":"Difficult cross-team coordination","c":[{"t":"heading","d":5,"p":{"lines":[78,79]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/transparent-cross-team-decision-making-using-rfcs\">Transparent Cross-Team Decision Making using RFCs</a>"}]}]},{"t":"heading","d":3,"p":{"lines":[80,81]},"v":"Cross Legal Entities Challenges","c":[{"t":"heading","d":4,"p":{"lines":[82,83]},"v":"Concern on legal liabilities or cross-company accounting","c":[{"t":"heading","d":5,"p":{"lines":[84,85]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/innersource-license\">InnerSource License</a>"}]}]}]},{"t":"heading","d":2,"p":{"lines":[86,87]},"v":"Grow","c":[{"t":"heading","d":3,"p":{"lines":[88,89]},"v":"Discovery Challenges","c":[{"t":"heading","d":4,"p":{"lines":[90,91]},"v":"Can't find matching projects","c":[{"t":"heading","d":5,"p":{"lines":[92,93]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/gig-marketplace\">Gig Marketplace</a>"},{"t":"heading","d":5,"p":{"lines":[94,95]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/innersource-portal\">InnerSource Portal</a>"}]},{"t":"heading","d":4,"p":{"lines":[96,97]},"v":"Difficult to find active projects","c":[{"t":"heading","d":5,"p":{"lines":[98,99]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/repository-activity-score\">Repository Activity Score</a>"}]}]}]},{"t":"heading","d":2,"p":{"lines":[100,101]},"v":"Scale","c":[{"t":"heading","d":3,"p":{"lines":[102,103]},"v":"Self Education/Improvement Challenges","c":[{"t":"heading","d":4,"p":{"lines":[104,105]},"v":"Not aware of InnerSource best practices","c":[{"t":"heading","d":5,"p":{"lines":[106,107]},"v":"<a href=\"https://patterns.innersourcecommons.org/p/maturity-model\">Maturity Model</a>"}]}]}]}]})</script>
 </body>
 </html>