Script to find upgradeable patterns (InnerSourceCommons#534)

* Script to identify upgradeable patterns based on their number of Known Instances
* Formatting changes to the 'Known Instances' section of some patterns. Allows for easier scanning of the new find_upgradeable_patterns.rb script

Author: spier

meta/README.md

@@ -12,6 +12,7 @@ The topics below cover information about how we define, operate, and upkeep this
 * [Style Guide](./pattern-style-guide.md) - Recommended conventions to use when writing patterns
 * [Glossary](./glossary.md) - Defines essential terms that are commonly used when writing new patterns.
 * [Board Reports](./boardreports) - The Patterns Working Group submits a report to the Board of the InnerSource Commons Foundation on a quarterly basis. This folder contains all reports that the Patterns Working Group has created.
+* [Scripts](./scripts) - Scripts that help us with the maintenance of our patterns.
 
 ## Unfinished documentation
 

meta/scripts/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+gem 'commonmarker'

meta/scripts/find_upgradeable_patterns.rb

@@ -0,0 +1,84 @@
+require 'rubygems'
+require 'bundler/setup'
+Bundler.require(:default)
+
+require 'pp'
+
+# ------------------------------------------------------------------------------------------------------------
+# This script scans all patterns in /patterns/1-initial and /patterns/2-structured.
+# Based on the number of Known Instances in the pattern, it suggests which patterns that might be ready to be leveled-up.
+#
+# The number of Known Instances are only one of the [requirement](https://github.com/InnerSourceCommons/InnerSourcePatterns/blob/main/meta/contributor-handbook.md#requirements-level-2---structured) 
+# for our patterns to reach the next level. Therefore reading the pattern and the level requirements in detail is still required
+# to decide whether or not a pattern can be pushed to the next level.
+
+# NOTE: This script and `/book/scripts/generate_toc.rb` have some overlap in how they are parsing markdown.
+# However the overlap seemed minimal, so I opted not to do any deduplication of code.
+# ------------------------------------------------------------------------------------------------------------
+
+# Count Known Instances in a pattern
+# - return 0 if the section does not exist, or does not contain the expected list structure
+# - return <count of Known Instances>
+def count_known_instances(file)
+  section_nodes = collect_section_nodes(file, "Known Instances")
+  list_nodes = []
+  # pick the first list in the "Known Instances" section, and return the number of elements in that list.
+  # CAUTION: this assumes a certain structure across all patterns. Therefore fairly brittle.
+  list_nodes = section_nodes.select {|n| n.type == :list}
+
+  known_instances_count = 0
+  known_instances_count = list_nodes.first.count if !list_nodes.first.nil?
+
+  return known_instances_count
+end
+
+def collect_section_nodes(file, section_title)
+  markdown = open(file).readlines().join
+  doc = CommonMarker.render_doc(markdown)
+
+  title_found = false
+  section_nodes = []
+  
+  doc.walk do |node|
+    if node.type == :header
+      if title_found == false
+        node.each do |subnode|
+          if subnode.type == :text and subnode.string_content == section_title
+            title_found = true
+          end
+        end
+      # stop the recursion once the next header is reached
+      # TODO: is this correct, or should we check if this is another `##` header, rather than any header?
+      else
+        break 
+      end
+    # once the title has been found, collect all nodes up to the next header
+    elsif title_found == true 
+      section_nodes << node
+    end
+  end
+
+  return section_nodes
+end
+
+
+# Main block
+
+puts "## Initial => Structured"
+puts "## 1-Initial patterns primed for upgrade to 2-Structured (based on Known Instances only)"
+l1_patterns = Dir["../../patterns/1-initial/*.md"]
+
+l1_patterns.each do |file|
+  known_instances_count = count_known_instances(file)
+  puts "#{known_instances_count} | #{file}" if known_instances_count >= 1
+end
+
+puts "\n"
+puts "## Structured => Validated"
+puts "## 2-Structured patterns primed for upgrade to 3-Validated (based on Known Instances only)"
+l2_patterns = Dir["../../patterns/2-structured/*.md", "../../patterns/2-structured/project-setup/*.md"]
+
+l2_patterns.each do |file|
+  known_instances_count = count_known_instances(file)
+  puts "#{known_instances_count} | #{file}" if known_instances_count >= 3
+end

patterns/1-initial/governance-levels.md

@@ -83,6 +83,8 @@ Examples of promoting the model names (3) are:
 
 ## Known Instances
 
+* Flutter Entertainment
+
 ![InnerSource Pyramid used by Flutter Entertainment](../../assets/img/flutter-pyramid.svg)
 
 Flutter Entertainment define an [InnerSource Pyramid](https://innersource.flutter.com/how/) to describe 3 different InnerSource operating models: Readable Source, Guest Contributions and Maintainers in Multiple Teams. Each name is centrally documented. The use of these names is encouraged via repeated usage, direct training and categorisation of each InnerSource project.

patterns/1-initial/incubator-pipeline.md

@@ -60,7 +60,7 @@ This pattern was inspired by things like the Apache Software Foundation's incuba
 
 ## Known Instances
 
-Being implemented at U.S. Bank.
+* Being implemented at **U.S. Bank**.
 
 ## Status
 

patterns/1-initial/introducing-metrics-in-innersource.md

@@ -92,7 +92,7 @@ Continued monitoring of these metrics will help middle management and developers
 
 ## Known Instances
 
-Santander Bank
+* **Santander Bank**
 
 ## Status
 

patterns/2-structured/dedicated-community-leader.md

@@ -58,7 +58,7 @@ Having excellent and dedicated community leaders is a precondition for the succe
 
 ## Known Instances
 
-_BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding.
+* _BIOS at Robert Bosch GmbH_. Note that InnerSource at Bosch was, for the majority, aimed at increasing innovation and to a large degree dealt with internal facing products. This pattern is currently not used at Bosch for lack of funding.
 
 ## Alias
 

patterns/2-structured/document-your-guiding-principles.md

@@ -121,6 +121,10 @@ All Trusted Committers of a project are published.
 
 ## Known Instances
 
+* Europace AG
+* GitHub
+* Robert Bosch GmbH
+
 ### Europace AG
 
 The InnerSource principles listed in the Solution above are mostly based on Europace's experience.