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

spier · 2020-12-05T10:23:32Z

This PR is the cleaned-up version of the previous PR #217.

The book generated from this branch is available here, to demo that it works:
https://innersourcecommons.gitbook.io/innersource-patterns/v/book-creation/

After merging this PR to master, a couple of things are still required to make sure that the gitbook gets generated correctly.

Release steps (1st release only)

cover image
- create cover image, and upload that to book/innersource-patterns-book-cover.jpg
- use cover image in the avatar of the book as well
- add license/attribution of that image
enable the "Edit on GitHub" feature (when readers of the book find a mistake, they can click "Edit on GitHub" and are taken directly to the correct .md page in our repo, where they can propose a fix as a PR)
remove all variants of the book that are not needed anymore (generated from branches book and book-creation
reconfigure the gitbook integration
- build from InnerSourcePatterns (upstream), rather than from spier’s fork (probably only a TC can do that)
- release from master branch, rather than from book branch (exclude the book branch so that it is not shown as different version in gitbook any more)
- make sure that the GitHub action to generate the ToC works fine on InnerSourcePatterns (upstream)
remove the “unlisted” flag from the book - we may only want to do this after we have configured a Custom Domain? (see below)
- while building the book I didn’t want changes to be picked up by the Google Search
- once we go live, we want to be found i.e. we should remove the “unlisted” flag

Nice to have

set up Google Analytics for the book (so that we know how often which pattern gets viewed)
- the Analytics that gitbook itself provide are not good enough
- we might try this out but also have to validate if gitbook complies with any consent/legal requirements that might come with the use of Google Analytics
nicer URLs/domain (see Custom Domain explanation)
- innersourcecommons.gitbook.io/innersource-patterns/ (once we change to build from the master branch)
- when we can configure our domain accordingly, we can also use a nicer URL e.g. books.innersourcecommons.org/innersource-patterns/
unpublish other gitbooks that were created from the InnerSource patterns repo to make it more clear what the official version is, and to improve the the SEO of the book
- e.g. Daniel’s experiment - done
try out slack integration for our gitbook - "Search your documentation directly from Slack with a special /gitbook command."

…s repo

spier · 2020-12-05T10:50:24Z

Hi @lenucksi, this is ready for prime time 🎉

If you have time then I would like to show you how it works, to make sure that somebody else besides me has that knowledge.

Also I need you in order to reconfigure the gitbook integration to build from this repo, rather than from my fork and some other config actions that a TC is required for.

gruetter · 2020-12-05T12:45:51Z

I love how the book turned out, @spier ! Very clean and easy to navigate: Kudos to all who were involved!

gruetter

Looks good, all in all. That said, I have made a couple of suggestions for your consideration.

book/contribute-to-this-book.md

book/introduction.md

gruetter · 2020-12-05T13:57:51Z

book/introduction.md

+
+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.


In my experience (thus far), silos never quite go away - they are just made more "permeable". Not sure we should mention this here but I feel we need to be careful setting the right expectations.

Same as above: I got this text from https://innersourcecommons.org, section "What is InnerSource?"

After reviewing all other comments, I noticed that this comment and the two comments below are all modifying text that I copied from somewhere else within the ISC.

In order to get the book released quickly I would therefore propose the following:

we resolve these 3 comments (i.e. leave the text as is)

get the book released

After that if you want to improve these descriptions, maybe you could open new PRs against the innersourcecommons.org or InnerSourcePatterns repo, and then we can port those changes into the book after that gets merged.

What do you think?

@gruetter if you can give me the green light on the approach highlighted in my last comment above, then I could get the first version of the book released over the weekend. So if you have any time to review this, would be much appreciated.

book/introduction.md

gruetter · 2020-12-05T14:05:54Z

book/introduction.md

+
+Patterns are a way of describing a repeatable, proven solution to a problem with 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 you are left with after the solution is applied).
+
+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.


Suggested change

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.

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. Pattern descriptions are subdivided into the following sections: Title, Patlet, Problem Statement, Context, Forces, Solutions and Resulting Context.

This text comes from here: https://github.com/InnerSourceCommons/InnerSourcePatterns#what-are-innersource-patterns

But again, I am happy to change it :)

gruetter · 2020-12-05T14:08:21Z

book/introduction.md

+
+## 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.


Proposal: s/immovable/invariable or s/immovable/fixed or s/immovable/immutable

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

Not sure I grok this. How would a potential user add a constraint to the pattern? Do we rather mean: "... that must be considered before applying the pattern"?

This description comes from https://github.com/InnerSourceCommons/InnerSourcePatterns#how-can-you-use-innersource-patterns

book/introduction.md

book/contribute-to-this-book.md

Co-authored-by: Georg Grütter <gruetter@gmail.com>

book/introduction.md

Co-authored-by: Georg Grütter <gruetter@gmail.com>

book/introduction.md

spier · 2020-12-12T09:59:44Z

Pulling this out into a global comment, rather than burying it in one of the review threads.

As @gruetter has already approved the PR and left the feedback as suggestions, I will move ahead like this:

I won't work in the feedback about the text in book/introduction.md for the time being, given that I got the wording for that straight from here, and here. We can still make the changes outside of that PR, but int hat case I would suggest to change the original sources as well, to stay consistent in our wording and messaging.
I will use best judgement to work in all other feedback, and bring the PR into a mergeable state
Finally I will reconfigure the gitbook integration, to make it work from master (see initial message in this PR)

I am planning to make these changes tomorrow (Sunday).

spier · 2020-12-13T16:18:33Z

Not sure what happened in a389c9f. Probably got created by gitbook when I set up the GitHub-gitbook integration again for testing purposes. I will likely refer that commit or send a new PR.

This reverts commit a389c9f.

spier and others added 2 commits December 5, 2020 11:18

add all files required to build a gitbook from our InnerSourcePattern…

73ab4dd

…s repo

Writing new ToC for the book

38f5ae4

spier changed the title ~~Publish level 2/3 patterns as a gitbook automatically~~ Publish level 2+3 patterns as a gitbook automatically Dec 5, 2020

spier added 2 commits December 5, 2020 11:43

[docs] improved documentation in the the github action workflow

21a337b

Prepare GHA for build from 'master'

7a5e5df

spier marked this pull request as ready for review December 5, 2020 10:47

spier requested review from cewilliams, gruetter, lenucksi, NewMexicoKid and nyeates as code owners December 5, 2020 10:47

spier mentioned this pull request Dec 5, 2020

[Outdated] Producing a gitbook out of the patterns in maturity Structured/Validated #217

Closed

gruetter approved these changes Dec 5, 2020

View reviewed changes

spier commented Dec 5, 2020

View reviewed changes

book/contribute-to-this-book.md Outdated Show resolved Hide resolved

spier and others added 3 commits December 5, 2020 17:39

Adding specific recommendation to add a Known Instance to a pattern

72f5dd2

Fix spelling in book/introduction.md

ecb93a5

Co-authored-by: Georg Grütter <gruetter@gmail.com>

Fix spelling in book/introduction.md

5f9ac98

Co-authored-by: Georg Grütter <gruetter@gmail.com>

spier commented Dec 5, 2020

View reviewed changes

book/introduction.md Outdated Show resolved Hide resolved

spier and others added 4 commits December 5, 2020 17:44

Use "apply" rather than "reuse"

896b07f

Change company to organization

6e22a3a

Co-authored-by: Georg Grütter <gruetter@gmail.com>

Update book/introduction.md

70812d7

Co-authored-by: Georg Grütter <gruetter@gmail.com>

Update book/introduction.md

02d6a46

Co-authored-by: Georg Grütter <gruetter@gmail.com>

spier commented Dec 5, 2020

View reviewed changes

book/introduction.md Outdated Show resolved Hide resolved

spier added 2 commits December 5, 2020 19:01

simplify contribution language

731949a

fixing embeded image from the SAP InnerSource portal

a28c1dd

lenucksi added the (Self-) Hosting Everything around artifact rendering and presentation. label Dec 12, 2020

Explain a bit better which patterns are published in the book.

62aa19b

GitBook: [book-creation] 26 pages and 13 assets modified

a389c9f

Revert "GitBook: [book-creation] 26 pages and 13 assets modified"

857abb2

This reverts commit a389c9f.

spier merged commit 1169632 into InnerSourceCommons:master Dec 13, 2020

spier deleted the book-creation branch December 13, 2020 18:47

spier mentioned this pull request Dec 13, 2020

Enable all trusted committers to produce an ebook of proven patterns #173

Closed


		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.


		Patterns are a way of describing a repeatable, proven solution to a problem with 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 you are left with after the solution is applied).

		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.


		## 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.

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

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

Uh oh!

Conversation

spier commented Dec 5, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release steps (1st release only)

Nice to have

Uh oh!

spier commented Dec 5, 2020

Uh oh!

gruetter commented Dec 5, 2020

Uh oh!

gruetter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spier Dec 5, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spier commented Dec 12, 2020

Uh oh!

spier commented Dec 13, 2020

Uh oh!

Uh oh!

spier commented Dec 5, 2020 •

edited

Loading

spier Dec 5, 2020 •

edited

Loading