Merge pull request #70 from JustinGOSSES/main

added new metric: contribution-distance

Author: JustinGOSSES

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

@@ -81,4 +81,4 @@ Add your goals, questions, and metrics into this graph!  It will help you to see
 You may get new ideas of what metrics answer the questions you have or what additional goals your questions can support.
 See [CONTRIBUTING.md#metrics].
 
-[CONTRIBUTING.md#metrics]: https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/CONTRIBUTING.md#metrics
+[CONTRIBUTING.md#metrics]: https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/CONTRIBUTING.md#metrics

scripts/gqm_gen/README.md

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