Figure out documentation and help files

[TomasTomecek]

We can't agree on how we should handle help files, READMEs and such.

One idea is to store complete help files/README for each version which makes maintenance hard (you have to fix typo in every help file).

The other idea is to propose a better structure with tooling which would be able to compose complete documentation (help files) so we would avoid boilerplate.

We need to decide.

Ideas from: @phracek @rpitonak

@hhorak what would you suggest?

[bkabrda]

@TomasTomecek a proposal: how about we create code that would:

• Search <repo>/x.y/fedora/root for help files.
• If no help files are found there, search <repo>/x.y/root for help files.
• If no help files are found there either, search <repo>/root.
• If no help files are found there either (== there are no help files at all), fail.

I think this approach is easy to implement, would save us a lot of boilerplate (while providing a way to override the top-level files on version or version-system_variant basis) and potentially it could be used for other files as well. WDYT @hhorak @phracek @rpitonak?

[bkabrda]

FWIW I think we could also apply this approach to test/ directories.

[bkabrda]

Although with tests, we probably want to rather run tests from all the directories that are parents to current directory, so more like:

• Search /x.y/fedora/root for tests, run them if found.
• Search /x.y/root for tests, run them if found.
• Search /root, run them if found.

But this is a different issue than docs, so I won't spam this issue with this any more :)

[TomasTomecek]

Regarding tests, I hope we will be able to maintain a single test suite and run it against all images.

For docs, the issue is that you may have specific information for specific platforms (Fedora, 9.5 version, etc.). So the question is: do we want to build the manpage, or have a single file?

[bkabrda]

So you're basically saying that you'd rather have something like "this is the base for all the readmes" and "these are specific instructions that we need to add to line 35 of the top-level readme to generate a fedora-specific readme file", correct?

If so, would it make sense to have one top-level readme/manpage/whatever and have the subdirectories contain patches that would add the os/version specific stuff? E.g:

• <repo>/root/help.1
• <repo>/x.y/root/help.1.patch # add x.y specific info
• <repo>/x.y/fedora/root/help.1.patch # add fedora specific info to x.y version of the image

The assumption here is that the patches would be reasonably small (or wouldn't need to exist at all) - we could always implement this as well as the approach that I outlined in my first comment in case someone would have doc files that diverge a lot for specific version/os. But starting with just the patches approach would certainly be easy enough and make more sense. WDYT?

[TomasTomecek]

Slavku, that's exactly the problem: help pages for different versions/platforms may diverge.

I agree that the solution you are proposing with patches is pretty simple. The only fear I have is to edit patch files by hand, so I really hope that you have some automation in mind (e.g. make help-source would generate a source help file in markdown format, then you would edit to for particular version/platform and finally call make help-file-patch to create the patch file), so we don't have to edit patches manually.

[bkabrda]

Yeah, I just wanted to clarify that I understand the problem finally :)

I definitely don't want to make anyone write patches by hand, so I'll give this some thought in terms of how to automate this and then I'll do some POC so that we have something specific to discuss.

[TomasTomecek]

\o/

[hhorak]

My experience is that we can write scripts (aka help files) the way they are same for rhel/centos/fedora, and extract the differences to environment variables defined in the Dockerfile (Dockerfiles differ for every platform anyway). We aim to have the same user experiences for rhel-based, centos-based and fedora-based images in the end, so sharing the files is in line with that. Some missing features (say centos variant doesn't allow to do a_thing()) could be ignored like this then:

if [ "$MYSQL_VERSION" \>= "5.5" ]; then
  a_thing()
fi

Keeping the sources simple is also important for maintenance..

[hhorak]

As for the differences in README.md and such static files (which we also want to have shown on github for documentation purposes), this is not easy though.. We ended with using something like "for the examples bellow, we use rhscl/python-35-rhel7 as the image name"... and users will understand the image name needs to be changed if working with some other image..

[hhorak]

I find quite effective the way we started to share the building scripts -- git sub-modules, or how all versions share the only one test, like it is visible in case of postgresql:
https://github.com/sclorg/postgresql-container

We might also consider doing it like it's done here: https://github.com/openshift-s2i/s2i-go (one common directory with scripts and build with docker build -f Dockerfile .. (mind the .. trick).

Also adding guys who have experiences with maintaining the images with more versions and more variants: @omron93 @praiskup @pkubat

[bkabrda]

@hhorak thanks for all the provided info, that's helpful. Could you possibly have a look at https://github.com/container-images/container-image-template/pull/33 and say whether that seems to be a reasonable solution for the static files, e.g. help page? Thanks!

[bkabrda]

Alternatively to the approach proposed in https://github.com/container-images/container-image-template/pull/33, we could make the top-level help/README/whatever a template and make the version/os-specific directories provide values to fill in that template. That would probably be even easier to maintain and more readable, but would likely require more software installed on the side of maintainer (or we could create some crazy shell stuff to not require that).

E.g. the top-level help.md would be:

Some stuff

{{ os_specific_info }}

Some more stuff

And in x.y/fedora/root/help.md.values we'd have:

os_specific_info="This is some info specific to Fedora"

And e.g. x.y/centos/root/ wouldn't need to contain the values at all, since there wouldn't be any centos-specific info.

Would that make more sense?