Version the Guides

[alohr51]

Feature description

We need to start versioning the guides.

Feature design or visual mockup

From the convo below we'll go with the approach of consolidating the repos' into 1 Guides repo.

Then we can version them by creating a single release-0.x branch on the guide repo when a release of Kabanero is cut.

That way when we create the console image the build will checkout the proper release-0.x branch from the guide repo.

• The build will need a new parameter GUIDE_RELEASE_BRANCH

Updating a previous releases' guide

To update a guide for a previous release, it will be as simple as putting that change in the proper release-0.x branch (and master if it makes sense)

Example release flow

1. Kabanero 0.7.0 is cut
2. Create the release-0.7 branch on the Guides repo
3. Build the console image and specify release-0.7 branch for the GUIDE_RELEASE_BRANCH parameter
4. The image build automation will clone the Guide repo and git checkout release-0.7
5. image build automation finishes creating the image with proper versioned guides.

[alohr51]

Entertaining the idea of moving to a single repository for the Guides. This would help make the versioning easier.

Pros:

• Easy to version entire repo (includes all guides)
• Would simplify our existing automation
  • No need for GitHub PAT since its only cloining 1 repo isntead of 15+
  • Can remove the ruby automation since it was needed to use the github API to decide which guide repos to clone, not we don't need to do that.
• Easier for downstream projects to copy all the guides if wanted.

Cons:

• Lose access control on a per guide basis - access to the guide repo means access to all guides
• Guide clonging is a all or none, can't just clone 1 guide if that's all you need.
• Repo might get too large with 50+ or 100+ guides, worst case is we have 2 repos then. But this is a big if the guides are pretty small.

[alohr51]

@jantley-ibm @bschrammIBM @SueChaplain what do you think about moving to a single repo for guides?

[bschrammIBM]

Single repo is a good idea - I don't think many people in the community have provided PRs for the Guides anyways.

[jantley-ibm]

You make good points about access control and cloning excess, but I think we gain more than we lose. Just requires a little vigilance that people don't muck around in each other's content.

[SueChaplain]

Agree this approach will be easier to maintain longer term. Note that since each guide is generally between 1-5 artifacts, even if it grows to 100 guides is will be a relatively small repo.

Migration from A -> B will need some forethought to avoid breaking links between guides and between guides/docs.

[alohr51]

New Guides repo is here: https://github.com/kabanero-io/guides