You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Change to subfolder structure (path in URL) e.g. "p/innersource-portal"
* Improve documentation of the book generation. incl description of book-staging
# How to generate the InnerSource Patterns gitbook
2
2
3
-
Whenever changes to the [InnerSource Patterns][InnerSourcePatterns] GitHub repository are made, a new version of our InnerSource Patterns book is published at gitbook.com.
4
-
5
-
The files in the `./book` folder contain generator scripts and some extra content required to create our gitbook.
3
+
Whenever changes to the [InnerSource Patterns][InnerSourcePatterns] GitHub repository are made, a new version of our InnerSource Patterns book is published at [patterns.innersourcecommons.org][book_production].
6
4
7
5
## Where is the book published?
8
6
9
7
The most up-to-date version of the book is available for readers/consumers at [patterns.innersourcecommons.org][book_production].
10
8
11
-
We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes.
9
+
We also have a [Staging version][book_staging], used by the editors/producers of the book for testing purposes. If you want to make any structural changes to the book, please send a PR to merge your changes into the `book-staging` branch. That way we can test your changes on the Staging version first, before they go live.
12
10
13
11
## Which patterns are published?
14
12
15
-
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).
13
+
The book contains patterns of maturity **Structured** (Level 2) or **Validated** (Level 3). **Initial** (Level 1) patterns are not published in the book, because 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](../meta/contributor-handbook.md).
16
14
17
15
## How does it work?
18
16
17
+
The `./book` folder contains generator scripts and some extra content required to create the gitbook.
18
+
19
19
-`/.gitbook.yaml` - Holds basic configuration for the gitbook service. This never needs to be changed.
20
20
-`/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.
21
21
-`/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`.
@@ -27,15 +27,16 @@ In the book we publish the patterns of maturity **Structured** (Level 2) or **Va
27
27
28
28
These patterns are already publicly available in the [InnerSource Patterns][InnerSourcePatterns] GitHub repo. So why publish such a book at all?
29
29
30
-
We think there are a couple of good reasons to publish the InnerSource patterns as a gitbook:
30
+
There are a couple of good reasons to publish the InnerSource patterns as a gitbook:
31
31
32
32
* (consumers) have something that is “nicer” to read than things on GitHub
33
-
* (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
33
+
* (consumers) search for keywords across all patterns
34
34
* (consumers) export book as PDF and read on other devices
35
-
* (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
35
+
* (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, the URL of the pattern stay the same)
36
+
* (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
36
37
* (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 :)
37
38
* (producers) learn which patterns are most interesting for readers (e.g. through Google Analytics)
Copy file name to clipboardExpand all lines: book/toc.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ Instead edit toc_template.md
14
14
15
15
<imgsrc="./innersource-program-mind-map.png"title="InnerSource Patterns as a Mind Map">
16
16
17
-
## Patterns
17
+
## Patterns <aid="p"></a>
18
18
19
19
*[30 Day Warranty](../patterns/2-structured/30-day-warranty.md) - When accepting contributions from outside of your own team, there is a natural aversion to taking responsibility for code not written by the team itself. Through the 30 Day Warranty the contributing team consents to provide bug fixes to the receiving team, which will increase the level of trust between both teams and makes it more likely that contributions get accepted.
20
20
*[Common Requirements](../patterns/2-structured/common-requirements.md) - Common code in a shared repository isn't meeting the needs of all the project-teams that want to use it; this is solved through requirements alignment and refactoring.
0 commit comments