Publish level 2+3 patterns as a gitbook automatically (#242)

Adds all files required to build a gitbook from our InnerSourcePatterns repo.
The gitbook needs to be generated from master, so some configuration will be required after merging this to master.

Co-authored-by: Georg Grütter <[email protected]>

.gitbook.yaml

@@ -0,0 +1,5 @@
+root : ./
+
+structure:
+  readme: book/introduction.md
+  summary: book/toc.md

.github/workflows/book.yml

@@ -0,0 +1,36 @@
+name: Book ToC Generation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "master"
+
+jobs:
+  book-toc-generation:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        ref: ${{ github.head_ref }}
+
+    - uses: actions/setup-ruby@v1
+      with:
+        ruby-version: '2.6'
+
+    - name: Install ruby dependencies
+      run: |
+        cd book/
+        gem install bundler
+        bundle install
+
+    - name: Generate ToC
+      run: |
+        cd book/
+        ruby generate_toc.rb
+
+    - name: Commit new ToC to book/toc.md
+      uses: stefanzweifel/git-auto-commit-action@v4
+      with:
+        commit_message: Writing new ToC for the book

book/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

book/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'

book/README.md

@@ -0,0 +1,44 @@
+# How to generate the InnerSource Patterns gitbook
+
+Whenever changes to the [InnerSource Patterns][InnerSourcePatterns] GitHub repository are made, a new version of our InnerSource Patterns book is published at gitbook.com.
+
+The files in the `./book` folder contain generator scripts and some extra content required to create our gitbook.
+
+## Where is the book published?
+
+The most up-to-date version of the book is available for readers/consumers at [innersourcecommons.gitbook.io/innersource-patterns/][book_production].
+
+*NOTE:*
+The final URL of the book has not been determined yet.
+
+We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes.
+
+## Which patterns are published?
+
+In the book we publish the patterns of maturity **Structured** (Level 2) or **Validated** (Level 3). For more on these maturity levels see the [Contributor Handbook](../meta/contributor-handbook.md).
+
+## How does it work?
+
+- `/.gitbook.yaml` - Holds basic configuration for the gitbook service. This never needs to be changed.
+- `/book/toc.md` - An auto-generated table of contents (ToC) for the book i.e. a list of all pages and patterns that are part of the book. The ToC is what you see on the left-hand-side menu in gitbooks.
+- `/book/generate_toc.rb` - Takes patterns of maturity **Structured** and **Validated**, extracts title and patlet, and injects this info into `/book/toc_template.md`. The output is written to `/book/toc.md`.
+- `.github/workflows/book.yml` - A GitHub Action that triggers the execution of `/book/generate_toc.rb`.
+- `/book/introduction.md` - The introduction to our book. This content is what the reader sees first when they open the book. The current content is based on [README.md](../README.md). We may need to modify this content even further, to address the readers of the book more specifically, rather than the readers of our GitHub repository.
+- `/book/contribute-to-this-book.md` - Information about how to contribute to this book.
+
+## Objectives of the book
+
+These patterns are already publicly available in the [InnerSource Patterns][InnerSourcePatterns] GitHub repo. So why publish such a book at all?
+
+We think there are a couple of good reasons to publish the InnerSource patterns as a gitbook:
+
+* (consumers) have something that is “nicer” to read than things on GitHub
+* (consumers) have stable URLs for patterns i.e. even if the files move in the folder structure in the repo, the URL of the pattern stay the same
+* (consumers) export book as PDF and read on other devices
+* (producers) a motivation for pattern authors (and all contributors) to level up patterns from 1-initial, as only 2-structured and 3-validated are published in the book
+* (producers) a motivation for us to introduce more specific quality guidelines for level 2+3, so that we can be even more proud of the content in the book :)
+* (producers) learn which patterns are most interesting for readers (e.g. through Google Analytics)
+
+[InnerSourcePatterns]: https://github.com/InnerSourceCommons/InnerSourcePatterns
+[book_production]: https://innersourcecommons.gitbook.io/innersource-patterns/
+[book_staging]: https://innersourcecommons.gitbook.io/innersource-patterns-staging/v/book/

book/contribute-to-this-book.md

@@ -0,0 +1,27 @@
+# Contribute to this book
+
+You want to help us make this book better? That is awesome!
+
+The InnerSource Patterns book itself is an open source project, and welcomes any form of contribution. Nothing is too small!
+
+If you have never made a contribution to an open source project before, know that the InnerSource Patterns community is group of friendly people and with that a safe place to try it out :)
+
+## Before you get started
+
+As the sources for the InnerSource Patterns and this book are kept in a repository on GitHub, you will need a user account there to make edits and  suggestions to this book. If you don't have a user account at GitHub yet, head over to [github.com](https://github.com) and create one for free.
+
+## Different ways to contribute
+
+Here a few ways in which you can contribute:
+
+1. fix spelling, formatting, or other glitches that you notice in this book
+2. improve the content of an existing pattern (e.g. by adding a short description of how you are using a pattern as a _Known Instance_)
+3. contribute a new pattern, describing how you have overcome InnerSource-related challenges in your organization
+
+For (1) and (2) above you can simply hit the **Edit on GitHub** link that you see at the top of each page in the book. This will take you straight to the respective file in our GitHub repository, where you can suggest your changes.
+
+For (3) you need to clone the [InnerSourcePatterns](https://github.com/InnerSourceCommons/InnerSourcePatterns) repository, and add a new file with your suggested pattern. When making such larger contributions to this book please review our [CONTRIBUTING.md](../CONTRIBUTING.md) and also our [Contributor Handbook](../meta/contributor-handbook.md).
+
+## License of Contributions
+
+The contents of this repository are licensed under [CC-BY-SA-4.0](../LICENSE.txt). By contributing to this repository, you grant us (and everyone else for that matter) the right to use your contribution in accordance with that license.

book/generate_toc.rb

@@ -0,0 +1,89 @@
+require 'rubygems'
+require 'bundler/setup'
+Bundler.require(:default)
+
+require 'pp'
+
+# Extracts the value of a specific section from a markdown file
+def extract_section(file, section_title)
+  markdown = open(file).readlines().join
+  doc = CommonMarker.render_doc(markdown)
+
+  title_found = false
+  section_nodes = []
+
+  # once the header in question is found, extract all the text nodes from the
+  # subsequent paragaph
+  doc.walk do |node|
+    if node.type == :header
+      node.each do |subnode|
+        if subnode.type == :text and subnode.string_content == section_title
+          title_found = true
+        end
+      end
+    elsif node.type == :paragraph && title_found == true
+      node.each do |subnode|
+        section_nodes += extract_text(subnode)
+      end
+      break # stop the recursion once the paragraph has been processed
+    end
+  end
+
+  section_content = section_nodes.join("")
+  return section_content
+end
+
+# extracts the pure text content from this CommonMarker node, and its children.
+# returns an array of strings
+def extract_text(node)
+  section_nodes = []
+  if node.type == :softbreak
+    section_nodes << " "
+  elsif node.type == :text
+    section_nodes << node.string_content
+  else
+    node.each do |subnode|
+      section_nodes += extract_text(subnode)
+    end
+  end
+  return section_nodes
+end
+
+
+def generate_patterns_overview(patterns)
+  pattern_overview = Hash.new()
+
+  patterns.each do |file|
+    title = extract_section(file, "Title")
+    patlet = extract_section(file, "Patlet")
+    pattern_overview[title] = {
+      :file => file,
+      :patlet => patlet
+    }
+  end
+
+  pattern_overview
+end
+
+
+# Main block
+
+TOC_TEMPLATE_FILE = "./toc_template.md"
+TOC_FILE = "./toc.md"
+
+## Generate list of patterns and sort them by name
+patterns = Dir["../patterns/2-structured/*.md","../patterns/2-structured/project-setup/*.md", "../patterns/3-validated/*.md"]
+pattern_overview = generate_patterns_overview(patterns)
+pattern_overview = pattern_overview.sort.to_h
+
+toc_snippet = pattern_overview.map{|title, values| "* [#{title}](#{values[:file]}) - #{values[:patlet]}"}
+toc_snippet = toc_snippet.join("\n")
+
+## Inject the list of patterns into the ToC template
+new_toc_content = open(TOC_TEMPLATE_FILE).readlines().join()
+new_toc_content = new_toc_content.gsub(/<<PATTERS_HERE>>/,toc_snippet)
+
+## Write the new ToC to file
+File.write(TOC_FILE, new_toc_content)
+
+puts "Written new ToC for book to #{TOC_FILE}"

book/introduction.md

@@ -0,0 +1,66 @@
+# Introduction
+
+<img src="./innersource-patterns-book-cover.jpg" title="InnerSource Patterns">
+
+{% hint style="info" %}
+This is an early release of the InnerSource Patterns book.
+You may still find broken links, spelling mistakes, or other errors in this book.
+Please help us to fix them to produce the best book possible :). Learn how to [contribute to this book](../book/contribute-to-this-book.md).
+{% endhint %}
+
+Welcome to the **InnerSource Patterns book**.
+
+This book contains InnerSource best practices codified in a specific format to make it easy to understand, evaluate, and apply them in your context. We call this format a **pattern**.
+
+These patterns have been collected by the [InnerSource Commons](http://innersourcecommons.org) community over many years. The most mature patterns have been published in this book. Mature in this context means that each pattern has been reviewed by members of the community, and has at least one known instance where this pattern has been used.
+
+In this introduction we explain [what InnerSource is](#what-is-innersource), [what a pattern is](#what-are-innersource-patterns), and [how to use these patterns](#how-can-you-use-innersource-patterns) in your organization.
+
+If you are using InnerSource in your company already and want to contribute your experiences to this book we would love to [welcome your contributions](../book/contribute-to-this-book.md)!
+
+## What is InnerSource?
+
+We define InnerSource as:
+
+> The use of open source principles and practices for software development within the confines of an organisation.
+
+InnerSource takes the lessons learned from developing open source software and applies them to the way companies develop software internally. As developers have become accustomed to working on world class open source software, there is a strong desire to bring those practices back inside the firewall and apply them to software that companies may be reluctant to release.
+
+For companies building mostly closed source software, InnerSource can be a great tool to help break down silos, encourage internal collaboration, accelerate new engineer on-boarding, and identify opportunities to contribute software back to the open source world.
+
+## What are InnerSource Patterns?
+
+Patterns are a way of describing a repeatable, proven solution to a problem within a context. They follow a simple form that helps people wanting to implement the solution to understand the constraints on the problem, the forces that must be balanced and the resulting context - the situation created by applying the solution.
+
+In inner sourcing, patterns can provide a way for the InnerSource Commons participants to concisely share information with each other, improving the practice of inner sourcing. Each of the patterns are divided into Title, Problem Statement, Context, Forces, and Solutions as their main sections.
+
+* [`What are patterns?` Youtube videos](http://bit.ly/innersource_patterns_videos) - Watch a set of 2-5 min youtube videos explaining InnerSource Patterns
+* [Pattern Discussion Webinar](https://youtu.be/i-0IVhfRVFU) - We held a webinar 2017-03-16 to live-discuss a donut pattern (go to 24:30 for the discussion). This is an illustration of the review process we follow. Also see the [June 1, 2017 O'Reilly Webinar on InnerSource Patterns](http://www.oreilly.com/pub/e/3884).
+* [Pattern Template](../meta/pattern-template.md) - View a skeleton inner source pattern to get an idea on what goes into a new pattern!
+* [Introduction to InnerSource Patterns (2016 Fall Summit presentation)](https://drive.google.com/open?id=0B7_9iQb93uBQbnlkdHNuUGhpTXc) - *Tim Yao and Padma Sudarsan* (PDF). Detailed pattern background and examples -- Get a detailed understanding of why and how to interact with our patterns. Also see the [Introduction to InnerSource Patterns (2017 Fall Summit)](https://drive.google.com/open?id=0B7_9iQb93uBQWmYwMFpyaGh4OFU) *Tim Yao and Bob Hanmer* (PDF).
+
+## How can you use InnerSource Patterns?
+
+Patterns must be used in a thoughtful manner. They cannot be blindly applied. In most cases, you will need to adapt the given solution to your own situation; but the information given in the pattern, defining the context (immovable constraints) and forces (constraints that can be changed and balanced against each other), should help you do this. Note that you will also need to determine if there are additional constraints (company context and company forces) that apply to your particular company/organization that must be added to the pattern (as a kind of filter). These additional constraints may require additional solution steps to be applied.
+
+The pattern form is useful for describing proven solutions but it can also be used for *brainstorming new solutions* where patterns are not yet established. This is, because the anatomy of a pattern provides a frame for thinking about a problem in a structured manner. You could also create a *donut pattern* (filling in the problem, context, forces and resulting context fields but leaving the solution blank) as a way of asking the InnerSource Commons community for help (to find a proven solution or to brainstorm things to try).
+
+## How to Contribute?
+
+Please refer to: [Contribute to this book](./contribute-to-this-book.md)
+
+## Credits
+
+This book is the result of many years of work from countless [Open Source Contributors](https://github.com/InnerSourceCommons/InnerSourcePatterns/graphs/contributors) from around the world. Their willingness to openly share the challenges that they faced in their companies, and how InnerSource has helped them address those challenges, make this book such a valuable resource for others on their InnerSource journey.
+
+We want to specifically mention the InnerSource Patterns Working Group. They have nurtured the quality of the InnerSource Patterns and helped others to contribute. Lastly they also compiled a selection of available patterns into this book.
+
+The title image of this book was created by [Sebastian Spier](https://spier.hu) and adapted from an image by [Tony Hisgett - Alhambra 6](https://www.flickr.com/photos/hisgett/29345405788/), available under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).
+
+ **Thank you to all contributors! And happy InnerSource Day :)**
+
+## Licensing
+
+![Creative Commons License](https://i.creativecommons.org/l/by-sa/4.0/88x31.png)
+
+InnerSourcePatterns by [InnerSourceCommons.org](http://innersourcecommons.org) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International](http://creativecommons.org/licenses/by-sa/4.0/) License.