Merge branch 'main' into governance-refactor

Author: jeffabailey

.github/workflows/gqm_update.yml

@@ -3,30 +3,38 @@ on:
   push:
     branches: [main]
     paths:
-      - 'measuring/goals/**'
-      - 'measuring/questions/**'
-      - 'measuring/metrics/**'
+      - "measuring/goals/**"
+      - "measuring/questions/**"
+      - "measuring/metrics/**"
 
   workflow_dispatch:
 jobs:
-    generateDiagram:
-      name: Generate Diagram
-      runs-on: ubuntu-latest
-      steps:    
-        - name: Checkout
-          uses: actions/checkout@v4
-        - name: Use Node.js
-          uses: actions/setup-node@v3
-          with:
-            node-version: '21.x'
-        - run: npm install --prefix ./scripts/gqm_gen
-        - run: npm run coverage-report --prefix ./scripts/gqm_gen
-        - name: Report NYC coverage
-          uses: sidx1024/[email protected]
-          with:
-            coverage_file: ".nyc_output/nyc-coverage-report/coverage-summary.json"
-        - run: npm run --silent start --prefix ./scripts/gqm_gen > ./new_gqm.md.tmp
-        - run: sh ./scripts/gqm_gen/gqm_update.sh ./new_gqm.md.tmp ./measuring/use_gqm.md > ./measuring/use_gqm.md.tmp
-        - run: rm -f ./new_gqm.md.tmp
-        - run: mv -f ./measuring/use_gqm.md.tmp ./measuring/use_gqm.md
-        - run: sh ./scripts/gqm_gen/gqm_commit.sh
+  generateDiagram:
+    name: Generate Diagram
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ssh-key: ${{ secrets.DEPLOY_KEY_SSH_PRIVATE_KEY }}
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "21.x"
+      - run: npm install --prefix ./scripts/gqm_gen
+      - run: npm run coverage-report --prefix ./scripts/gqm_gen
+      - name: Report NYC coverage
+        uses: sidx1024/[email protected]
+        with:
+          coverage_file: ".nyc_output/nyc-coverage-report/coverage-summary.json"
+      - run: npm run --silent start --prefix ./scripts/gqm_gen > ./new_gqm.md.tmp
+      - run: sh ./scripts/gqm_gen/gqm_update.sh ./new_gqm.md.tmp ./measuring/use_gqm.md > ./measuring/use_gqm.md.tmp
+      - run: rm -f ./new_gqm.md.tmp
+      - run: mv -f ./measuring/use_gqm.md.tmp ./measuring/use_gqm.md
+      - name: Commit GQM Diagram
+        working-directory: ./measuring
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .
+          git diff --staged --quiet || (git commit -m "Update Goals Questions Metrics Graph" && git push)

.gitignore

@@ -1,2 +1,3 @@
 # We want to ignore our vale StylesPath
 .github/vale/*
+ gqm*[pngmd]

measuring/metrics/contribution-distance.md

@@ -0,0 +1,39 @@
+[⬑ back to the overall graph](../use_gqm.md)
+
+# **Metric:** Contribution Distance
+
+**Synopsis**: Number of organizational hops from owning team to contributing team
+It can be useful to know not only when contributions to a repository are made, but the distance between the 
+owning team and contributing individual in terms of organizational distance. 
+
+**Unit of Measurement**: manager levels
+This is measured in terms of number of managers you have to move up in the hierarchy before you can go down to 
+the contribution team. For example, if the manager in common of both parties is two jumps up the chain, 
+then the distance is 2. Most contributions will be in-team and therefore are 0 distance. For a contribution
+to be "InnerSource", it has to be at least 1 distance.
+
+**Interpretation**: Contribution distance is a measurable proxy for collaboration 
+A repository with a pull request that has a high contribution distance is likely to be reflective of a 
+repository with more impact and more effective set up for collaboration. Repositories that have pull requests
+with a high contribution distance are on average probably more likely to be useful to others than repositories 
+with only a single short distance collaboration. 
+
+Collaboration distance and counts combined can also tell you something about the type of value a repository provides. 
+A repository with many pull requests of 1-2 distance is likely to be reflective of partner teams working closely 
+together to solve a shared problem. A repository with many pull requests of 3-4 distance but only a single 
+pull request from each contributor is likely to be reflective of a repository that is being used for information 
+sharing or as a reference. Contribution distance is a metric that can be combined with others to build up 
+a picture of the community around each repository where InnerSource contribution behaviors are occurring. 
+
+**Measuring**
+
+Measuring this metrics requires a mapping of your organization's hierarchy and a way to define whether the person 
+that submits each issue or pull request is a member of the owning team or not. There are likely multiple 
+ways to do each of these tasks and the best way will depend on your organization.
+
+As an example, Microsoft determines if an individual is on the "owning team" by finding the individual that approved 
+the majority of pull requests and then finding the manager that is accountable for that individual. 
+
+One possible pitfall is that manager and team relationships change over time. For this reason, it can be preferred 
+to measure contribution distance soon after the pull request is merged and then store the distance as 
+manager relationships will change over time degrading the data quality. 

measuring/metrics/number-of-innersource-repositories.md

@@ -0,0 +1,33 @@
+[⬑ back to the overall graph](../use_gqm.md)
+
+# **Metric:** Number of InnerSource repositories
+
+As projects adopt InnerSource, there are signs of such adoption on the corresponding source code repositories.
+Examples are the presences of a `CONTRIBUTING.md` file, a "How to Contribute" section on the `README.md` file or repository topics in GitHub such as `innersource`.
+
+One challenge with this metric, is defining an InnerSource repository, as there is no clear cut definition.
+Some companies may have strict requirements that define an InnerSource repository, while others may adopt a _self-declaration_.
+
+Another challenge is that companies that use (entirely or partially) the concept of a monorepo may need to find a different unit of measure to observe, as a single repository may be used for many projects or software packages.
+
+**Synopsis**: Number of source code repositories that adopt InnerSource 
+
+**Unit of Measurement**: Number of repositories 
+
+**Interpretation**: Comparing an absolute number to a range does not make sense in this context. Comparing percentages does make sense, but there's no strong base for comparison.
+
+e.g. 10% of repositories are InnerSource
+
+It's more interesting to observe this metric's trend over time.  
+
+**Measuring**
+
+Examples:
+- Measure the number of GitHub repositories tagged with the `innersource` topic.
+- Measure the number of repositories that are above a given threshold using an automated maturity score calculation
+
+## Related InnerSource Patterns
+- [InnerSource Portal](https://patterns.innersourcecommons.org/p/innersource-portal) - typically shows the number of InnerSource projects
+- [Repository Activity Score](https://patterns.innersourcecommons.org/p/repository-activity-score) - defines a score for ranking active projects, usable as a criteria to identify InnerSource repositories
+- [Standard Base Documentation](https://patterns.innersourcecommons.org/p/base-documentation) - describe common files used to document different aspects of InnerSource projects
+- [Maturity Model](https://patterns.innersourcecommons.org/p/maturity-model) - defines levels of maturity for InnerSource projects and can help classify a repository as InnerSource.

measuring/questions/adoption-trend.md

@@ -0,0 +1,12 @@
+[⬑ back to the overall graph](../use_gqm.md)
+
+# **Question:** What is the InnerSource adoption trend?
+
+This question is something an InnerSource program asks while fostering the adoption of InnerSource.
+Lack of adoption, or stagnant adoption may reveal that it is necessary to rethink the program strategy or investigate impediments.
+
+## Related Metrics
+
+| **Metric** | **How it answers the question** | **Gotchas** |
+| --- | --- | --- |
+| [Number of InnerSource repositories](../metrics/number-of-innersource-repositories.md) | The number of (source code) repositories that are directly related to the adoption of the practice. | Depending on how you define _InnerSource repositories_, it can report incorrect results |

measuring/questions/who-contributes.md

@@ -9,3 +9,4 @@ There are many types of contributions - e.g. code, documentation, discussion, et
 | **Metric** | **How it answers the question** | **Gotchas** |
 | --- | --- | --- |
 | [Code Contributions](../metrics/code-contributions.md) | Each code contribution represents a contributor to the InnerSource project. | There are other types of contributions beyond code. |
+| [Contribution Distance](../metrics/contribution-distance.md) | Measures how far apart in the organization each InnerSource contribution is. | Depends on accurate information on the organization's hierarchy mapped to contributor identity. |

measuring/use_gqm.md

@@ -2,7 +2,7 @@
 
 *An overview of the Goals, Questions, and Metrics (GQM) catalog.*
 
-This page works better in GitHub; [click here](https://bit.ly/3tOrsbO).
+Right-click on any node representing a goal, question, or metric to open a new tab with more detailed information.
 
 <!--- 
 
@@ -31,17 +31,40 @@ graph LR;
 
     subgraph GQM[Goals, Questions, Metrics]
 
-      find-projects.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//goals/find-projects.md'>Find InnerSource Projects</a>]
-    reduce-duplication.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//goals/reduce-duplication.md'>Reduce duplication</a>]
-    who-contributes.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//questions/who-contributes.md'>Who contributes to the InnerSource project?</a>]
-    who-uses.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//questions/who-uses.md'>Who uses the InnerSource project?</a>]
-    code-contributions.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/code-contributions.md'>Code contributions</a>]
-    usage-count.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/usage-count.md'>Usage count</a>]
+    %% begin nodes
+    find-projects.md[Find InnerSource Projects]
+    reduce-duplication.md[Reduce duplication]
+    adoption-trend.md[What is the InnerSource adoption trend?]
+    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]
+    number-of-innersource-repositories.md[Number of InnerSource repositories]
+    usage-count.md[Usage count]
+    %% end nodes
+
+    %% begin edges
     find-projects.md-->who-uses.md
     find-projects.md-->who-contributes.md
     reduce-duplication.md-->who-uses.md
+    adoption-trend.md-->number-of-innersource-repositories.md
     who-contributes.md-->code-contributions.md
+    who-contributes.md-->contribution-distance.md
     who-uses.md-->usage-count.md
+    %% end edges
+
+    %% begin clicks
+    click find-projects.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/goals/find-projects.md" "Find InnerSource Projects"
+    click reduce-duplication.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/goals/reduce-duplication.md" "Reduce duplication"
+    click adoption-trend.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/questions/adoption-trend.md" "What is the InnerSource adoption trend?"
+    click who-contributes.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/questions/who-contributes.md" "Who contributes to the InnerSource project?"
+    click who-uses.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/questions/who-uses.md" "Who uses the InnerSource project?"
+    click code-contributions.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/metrics/code-contributions.md" "Code contributions"
+    click contribution-distance.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/metrics/contribution-distance.md" "Contribution Distance"
+    click number-of-innersource-repositories.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/metrics/number-of-innersource-repositories.md" "Number of InnerSource repositories"
+    click usage-count.md "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/metrics/usage-count.md" "Usage count"
+    %% end clicks
+
   end
       subgraph Legend
         direction TB
@@ -54,10 +77,10 @@ graph LR;
         class goal,find-projects.md,reduce-duplication.md goals
 
         classDef questions stroke:orange,stroke-width:2px;
-        class question,who-contributes.md,who-uses.md questions
+        class question,adoption-trend.md,who-contributes.md,who-uses.md questions
 
         classDef metrics stroke:purple,stroke-width:2px;
-        class metric,code-contributions.md,usage-count.md metrics
+        class metric,code-contributions.md,contribution-distance.md,number-of-innersource-repositories.md,usage-count.md metrics
       end  
   
 ```

package-lock.json

@@ -2,11 +2,53 @@
 
 Creates a Mermaid diagram from Goal, Question, Metrics (GQM) Markdown files.
 
+The instructions below describe how to locally run 
+the script that builds the mermaid diagram. 
+A GitHub Actions will re-run this script at built time
+and regenerate the diagram, but it is good to run 
+locally to make sure it will build correctly.
+
+Be sure to also read the instructions in the 
+`measuring/use_gqm.md` file path.
+
+## Installation
+
+### Install mermaid CLI globally
+
+From this folder, follow instructions on the 
+[mermaid.js README](https://github.com/mermaid-js/mermaid-cli) to run in the terminal: 
+```
+npm install -g @mermaid-js/mermaid-cli
+```
+
+Install project specific node.js based on the package.json in this folder: 
+```
+npm install
+```
+
 ## Usage
 
 Builds the mermaid diagram and outputs it to stdout.
 
 ```bash
-npm install
-npm run --silent start
+npm run --silent start > gqm.md && mmdc --input gqm.md --output gqm.png
 ```
+
+Note that the file ending `.mmd` is not a typo. It is mermaid markdown file.
+
+This should generate a file called `gqm.png` or `gqm-1.png` in the same folder as this file.
+
+You will also end up with BOTH a `gqm.md` and a `gqm.mmd` file as the later is created upon running the script.
+
+## Files that impact the generation of the mermaid diagram
+
+Most of the diagram is generated by the `gqm.md` file but be sure to also 
+make changes in the files within the `measuring`, `questions`, and `goals` folders as appropriate. 
+You'll have to create a file for a new block and edit any file that mentions that new block. 
+For example, if you create a new metric, you'll want to create a new markdown file in the 
+metrics folder. Additionally, as there is an arrow that goes from that metric to a question, 
+you'll want to edit the table in the question file that talks to all the metrics that impact that question. A metric can be connected to one or more questions.
+
+### Warning
+Files that are referenced by the mermaid diagram must not use underscores `_` in their filenames. 
+Instead use hyphens `-`.