Merge remote-tracking branch 'origin/main' into core-team-improvements

Author: spier

.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/[email protected]
+      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/innersource-program-mind-map.png

@@ -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>
 

book/toc.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>
 

book/toc_template.md

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

pattern-categorization/.gitignore

@@ -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