Whenever changes to the InnerSource Patterns GitHub repository are made, a new version of the InnerSource Patterns book is published at patterns.innersourcecommons.org.
The latest version of the book is available for readers at patterns.innersourcecommons.org.
We also have a Staging version, used by the editors/producers of the book for testing purposes. If you want to make structural changes to the book, please contact us via a GitHub issue first.
The book contains patterns of maturity Structured (Level 2) or Validated (Level 3).
Initial (Level 1) patterns are not published in the book. Those are still subject to a lot of change, and have likely not even proven to work yet. For more on these maturity levels see the Contributor Handbook.
We use the gitbook.com service to host our book.
The /book folder contains generator scripts and extra content required to create the gitbook.
.github/workflows/book.yml- A GitHub Action that triggersgenerate_toc.rb./book/scripts/generate_toc.rb- Generates the table of contents (ToC) for the book. It takes patterns of maturity Structured and Validated, extracts title and patlet, and injects this info into/book/en/toc_template.md. The output is written to/book/en/toc.md. The ToC is what you see in the menu on the left in the gitbook./book/en/.gitbook.yaml- Holds basic configuration for the gitbook service./book/en/introduction.md- The introduction to our book. This is what the reader sees first when they open the book. Note: The current content is based on README.md./book/en/contribute.md- Explains how to contribute to this book./book/en/explore-patterns.md- Shows the mind map of all patterns. Allows readers to link to the mind map directly.- patterns content:
- The English patterns are in
/patterns - The translated patterns are in
/translation/<YOUR_LANGUAGE>1
- The English patterns are in
The book is generated in multiple languages.
The descriptions above are for the English book. You find the English content in /book/en.
For other languages the content is mirrored and translated to folders like /book/<YOUR_LANGUAGE>1.
For more on the translation process see these translation instructions.
The book is generated in multiple languages.
gitbook takes care of the markdown to HTML rendering for us. To do so, we need to provide a full list of all patterns that should be dipslayed in the book.
As the list of patterns grows over time, we generate the list automatically using /book/scripts/generate_toc.rb.
The script is triggered by the .github/workflows/book.yml workflow, which contains a hard-coded list of all languages for which we need to generate toc.md files.
If a new language is added, you need to modify this line in .github/workflows/book.yml and add the 2-letter language code of the language that you are adding.
These patterns are already publicly available in the InnerSource Patterns GitHub repo. So why publish such a book at all?
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) search for keywords across all patterns
- (consumers) export book as PDF and read on other devices
- (consumers) have stable URLs for patterns that can be used as references in other material e.g. from the Learning Path (i.e. even if the files move in the folder structure in the GitHub repo, we can keep the URL of the pattern in the book the same)
- (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)
Footnotes
-
Replace
<YOUR_LANGUAGE>with the 2-letter ISO 639-1 language code for your language. ↩ ↩2