Merge branch 'InnerSourceCommons:main' into main

Author: JustinGOSSES

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

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/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.
 
 <!--- 
 
@@ -34,26 +34,34 @@ graph LR;
     %% 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" _blank
+    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
 
@@ -69,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  
   
 ```
@@ -81,4 +89,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/gqm-1.png

@@ -9,7 +9,7 @@ const mdFilePath = process.env.npm_config_markDownFilePath || "../../measuring";
 const graph = getGQMFileLinks(mdFilePath);
 
 export function getLinkUrl(linkType: LinkType, file: string) {
-  const measuringUrl = "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring/";
+  const measuringUrl = "https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring";
   const url = `${measuringUrl}/${linkType.toLowerCase()}s/${file}`
   return url;
 }
@@ -127,7 +127,7 @@ export function getLinks(parsed: Commonmark.Node) {
 
 export function getNodeShapeSyntax(node: Node) {
   const nodeUrl = getLinkUrl(node.type, node.id)
-  const nodeLabel = `<a href='${nodeUrl}'>${node.label}</a>`;
+  const nodeLabel = `${node.label}`;
   switch (node.shape) {
     case 'rect':
       return `[${nodeLabel}]`;
@@ -150,16 +150,31 @@ export function generateMermaidDiagram(graph: Graph) {
     subgraph GQM[Goals, Questions, Metrics]\n
   `;
 
+  mermaidSyntax += "  %% begin nodes\n";
   nodes.forEach((node) => {
     const nodeSyntax = getNodeShapeSyntax(node)
     mermaidSyntax += `    ${node.id}${nodeSyntax}\n`
   });
+  mermaidSyntax += "    %% end nodes\n\n";
+  
+  mermaidSyntax += "    %% begin edges\n";
 
   edges.forEach((edge) => {
     const arrowSyntax: string = ArrowType.ARROW;
     mermaidSyntax += `    ${edge.from}${arrowSyntax}${edge.to}\n`;
   });
 
+  mermaidSyntax += "    %% end edges\n\n";
+
+  mermaidSyntax += "    %% begin clicks\n"
+
+  nodes.forEach((node) => {
+    const nodeUrl = getLinkUrl(node.type, node.id);
+    mermaidSyntax += `    click ${node.id} "${nodeUrl}" "${node.label}"\n`; 
+  });
+
+  mermaidSyntax += "    %% end clicks\n\n"
+
   const goalsList = nodes.filter(n => n.type == LinkType.GOAL).map(n => `${n.id}`).join(',');
   const questionsList = nodes.filter(n => n.type == LinkType.QUESTION).map(n => `${n.id}`).join(',');
   const metricsList = nodes.filter(n => n.type == LinkType.METRIC).map(n => `${n.id}`).join(',');

scripts/gqm_gen/gqm_commit.sh

@@ -163,6 +163,8 @@ When configuring repository creation settings at the Organization Level, it's es
 
 *Depending on the type of Github instance you are using, the configurations options available may be what are shown below or there might not be an option for "internal" visible repositories.*
 
+| Repository creation | Description | Recommendation |
+| --- | --- | --- |
 | Disabled | Members will not be able to create repositories. | Discourages repository creation and may hinder InnerSource practices. Consider enabling creation for collaboration. |
 | Members can create repositories | Members are allowed to create repositories, but with restrictions on the types available (public, private, internal). | Encourage the creation of repositories while specifying the types that align with your organization's guidelines. |
 | ┣ Public | Members can create public repositories visible to everyone on GitHub. | Promote open sharing and collaboration with both internal and external stakeholders. |

scripts/gqm_gen/index.ts

@@ -4,7 +4,7 @@
 
 Este libro busca proporcionar información sobre a xestión de distintos aspectos indispensables á hora de empregar InnerSource nas empresas.
 
-É o resultado dun proceso aínda en marcha, no que calquera persoa está convidada a contribuír de calquera xeito posible. As aportacións en forma de ideas, comentarios, correccións de erros tipográficos, ou mesmo cambios en parágrafos ou seccións enteiras, serán benvidas. Este repositorio ten como obxectivo aportar coñecemento especializado desde a industria de maneira que sexa útil a terceiros/as. Para isto, estamos na procura activa de revisores/as que poidan colaborar neste proceso e expresamos o noso agradecemento a aquelas persoas que xa fixeron algunha contribución ao libro.
+É o resultado dun proceso aínda en marcha, no que calquera persoa está convidada a contribuír de calquera xeito posible. As achegas en forma de ideas, comentarios, correccións de erros tipográficos, ou mesmo cambios en parágrafos ou seccións enteiras, serán benvidas. Este repositorio ten como obxectivo achegar coñecemento especializado desde a industria de maneira que sexa útil a terceiros/as. Para isto, estamos na procura activa de revisores/as que poidan colaborar neste proceso e expresamos o noso agradecemento a aquelas persoas que xa fixeron algunha contribución ao libro.
 
 Pode atopar máis información sobre este proceso na [sección de contribucións](https://github.com/dicortazar/managing-inner-source-projects/blob/master/CONTRIBUTING.md).