Skip to content

Script to find upgradeable patterns #534

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 12, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions meta/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
7 changes: 7 additions & 0 deletions meta/scripts/Gemfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

gem 'commonmarker'
84 changes: 84 additions & 0 deletions meta/scripts/find_upgradeable_patterns.rb
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions patterns/1-initial/governance-levels.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion patterns/1-initial/incubator-pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion patterns/1-initial/introducing-metrics-in-innersource.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ Continued monitoring of these metrics will help middle management and developers

## Known Instances

Santander Bank
* **Santander Bank**

## Status

Expand Down
2 changes: 1 addition & 1 deletion patterns/2-structured/dedicated-community-leader.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 4 additions & 0 deletions patterns/2-structured/document-your-guiding-principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down