Outdated documentation

[frenzymadness]

Who or what procedure is responsible for updating documentation on Docker hub or Openshift docs? I am asking because both seem to be outdated:

• https://hub.docker.com/r/centos/python-36-centos7
• https://docs.openshift.com/container-platform/3.11/using_images/s2i_images/python.html

@torsava any thoughts who to ask?

[torsava]

@pkubatrh Hey, do you have rights to change these? Or do you know who does?

[frenzymadness]

And why it's not done automatically especially for docker hub…

[pkubatrh]

The docker hub descriptions should be done automatically on push to master, but seems like the slaves do not have latest scripts that fixed an issue with image tagging so the job fails before it can run the update. @hhorak can you refresh the jobs?

@bparees might know who the correct person to contact is regarding the Openshift docs

[bparees]

@bmcelvee can help you w/ the docs,or you can make a PR directly:

the 3.11 docs are here (master branch for now, though master branch may become 4.x soon) https://github.com/openshift/openshift-docs/blob/master/using_images/s2i_images/python.adoc

i'm not sure if we have equivalent content for 4.x, it would be in this branch if so: https://github.com/openshift/openshift-docs/tree/enterprise-4.1

[frenzymadness]

@bparees Does it make sense to maintain the documentation in two places? We update it fairly often and send a PR every time we do so does not scale.

[bparees]

@bparees Does it make sense to maintain the documentation in two places? We update it fairly often and send a PR every time we do so does not scale.

not sure it's a scaling issue but i can understand it's more work than you'd want to deal with. I see a couple options:

1. assuming we allow it (and i think we do) update the official docs to be more general/hand-wavy, and have them link out to the github docs for "current specifics". Just keep in mind that if behavior changes between versions, you're going to have old openshift docs potentially pointing to current python image docs which are not valid for the python image the customer is actually using. So you might either want the official docs to point to specific commits/branches, or at least include caveats in the offcial docs that what you're referencing isn't necessarily an exact match to what the customer is running.

2. stop maintaining the github docs and link to the official openshift docs instead (and maintain those). This is probably slightly less desirable from a community/upstream-first mentality.

@bmcelvee can help you pick the best path forward.

[frenzymadness]

I have related (and probably stupid) questions: How a container image finds its way from Docker hub, Fedora registry, or Red Har catalog to OpenShift? If I understand it correctly, users can import any container image they want but OpenShift also offers some defaults and those default images are documented in the OpenShift documentation. It this assumption correct? If so, Who and how often updates the images? Would it make sense to update also docs together?

I don't know much about OpenShift but when we release a new image, documentation is updated at the same time automatically (Centos - Docker hub) or manually (Fedora and Red Hat registries).

[bparees]

If I understand it correctly, users can import any container image they want but OpenShift also offers some defaults and those default images are documented in the OpenShift documentation.

more or less correct, yes.

If so, Who and how often updates the images?

SCL team updates the images by publishing new versions to registry.redhat.io. Assuming they are just updating an existing tag, new openshift installs will pick up the image automatically. Existing installs can optionally "refresh" their imagestream imports to pick up the new version.

The flow is as follows, for example for the python image:

1. SCL image repo defines this file: https://github.com/sclorg/s2i-python-container/blob/master/imagestreams/python-rhel7.json

which includes, for example, this specific stanza to pull in the "3.8" tag: https://github.com/sclorg/s2i-python-container/blob/master/imagestreams/python-rhel7.json#L32-L48

2. SCL team maintains this entry in openshift/library to get their imagestreams imported into openshift/library: https://github.com/openshift/library/blob/master/official.yaml#L59

3. openshift/library does automatic imports based on that file, resulting in this file being pulled into the repo: https://github.com/openshift/library/blob/master/official/python/imagestreams/python-rhel7.json

which is basically just a copy of the imagetream yaml file from the SCL repo.

4. the cluster-samples-operator repo syncs a subset of content from openshift/library, including in this case the SCL python imagestream yaml: https://github.com/openshift/cluster-samples-operator/blob/master/tmp/build/assets/operator/ocp-ppc64le/python/imagestreams/python-rhel7.json

(note, that file looks like it might be an older version, as it does not contain the 3.8 tag, only the 3.6 tag. I'm not sure if that's intentional or @gabemontero just needs to rerun the import to pick up the newer content).

The samples operator ships with openshift and installs its content (imagestreams+templates) on the cluster, which is what finally results in the imagestreamtag existing on the cluster and being referenceable by users out of the box.

Users can, as you note, also create their own imagestreamtags to pick up any image they want from any docker image registry, but this special set of content is annotated to be used as s2i builder images, as well as being referenced from the example templates which ship that easily let users get an application running quickly.

Would it make sense to update also docs together?

since most likely the docs would only need to change when new minor versions (e.g. a future 3.9) are being picked up, yes updating the openshift docs when the samples operator is picking up a new version(tag) of an image makes sense.

[hhorak]

4. the cluster-samples-operator repo syncs a subset of content from openshift/library, including in this case the SCL python imagestream yaml:
   https://github.com/openshift/cluster-samples-operator/blob/master/tmp/build/assets/operator/ocp-ppc64le/python/imagestreams/python-rhel7.json

(note, that file looks like it might be an older version, as it does not contain the 3.8 tag, only the 3.6 tag. I'm not sure if that's intentional or @gabemontero just needs to rerun the import to pick up the newer content).

What I'm wondering is when this import happens -- is it once for each major OCP version or regularly for minor updates? I.e. if we release a new version of the python container after say 4.3 is released GA, will the new version of the python stream be available in some further 4.3.x release or just in 4.4.x?

[bparees]

What I'm wondering is when this import happens -- is it once for each major OCP version or regularly for minor updates? I.e. if we release a new version of the python container after say 4.3 is released GA, will the new version of the python stream be available in some further 4.3.x release or just in 4.4.x?

@gabemontero would have to comment on exactly when he does refresh imports to the samples operator, but in general we do not add new imagestreamtags (e.g. adding a new minor version tag like "3.7" when the prior latest was "3.6") except on minor OCP version boundaries. So for example if OCP 4.5's samples operator only included a "3.6" tag, it will never get a "3.7" tag, but OCP4.6 would include the "3.7" tag, if "3.7" was available at the time that 4.6 hit feature freeze.

so to directly address your scenario, the new version(new tag) would only be available in 4.4.x. But new versions of existing tags (e.g. an updated version of the 3.6 tag) would be picked up by customers who are freshly installing 4.3.x because we just import whatever the tag currently points to, at install time.

[hhorak]

Ok, got it, thanks @bparees

[gabemontero]

On Tue, Jul 14, 2020 at 11:34 AM Ben Parees [email protected] wrote:

What I'm wondering is when this import happens -- is it once for each major OCP version or regularly for minor updates? I.e. if we release a new version of the python container after say 4.3 is released GA, will the new version of the python stream be available in some further 4.3.x release or just in 4.4.x?

@gabemontero https://github.com/gabemontero would have to comment on exactly when he does refresh imports to the samples operator, but in general we do not add new imagestreamtags (e.g. adding a new minor version tag like "3.7" when the prior latest was "3.6") except on minor OCP version boundaries. So for example if OCP 4.5's samples operator only included a "3.6" tag, it will never get a "3.7" tag, but OCP4.6 would include the "3.7" tag, if "3.7" was available at the time that 4.6 hit feature freeze.

so to directly address your scenario, the new version(new tag) would only be available in 4.4.x. But new versions of existing tags (e.g. an updated version of the 3.6 tag) would be picked up by customers who are freshly installing 4.3.x because we just import whatever the tag currently points to, at install time.

Yep the methodology @bparees described is still the one in effect.

—

You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/sclorg/s2i-python-container/issues/324#issuecomment-658249967, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA3NU5GTW5NMFAC3DHKHZPDR3R3IBANCNFSM4HORO5SQ .

[frenzymadness]

Would it make sense to update also docs together?

since most likely the docs would only need to change when new minor versions (e.g. a future 3.9) are being picked up, yes updating the openshift docs when the samples operator is picking up a new version(tag) of an image makes sense.

And that might not be true. For example, when we implement a new feature we do it for all supported images (all Pythons and platforms combinations) when it's possible and reasonable and the new feature is usually reflected in the documentation.

And then, for example, @pkubatrh releases a new rhscl/python-27-rhel7 image which has the same version and the only difference is in the release number (2.7-83 → 2.7-84) but the newer image contains a new feature which means that the documentation should be updated as well.

Does it make sense?

[bparees]

Does it make sense?

yeah it makes sense, that sort of scenario is what i was hedging against with "most likely". Certainly new behaviors might be introduced and effectively "backported' to the older framework versions, but for the most part i'd expect these images to be pretty stable at this point. And of course it's always a choice whether you backport new behaviors to the older versions, or just introduce it in the newer versions.

But anyway if maintaining the docs in two places is a significant concern for the team (and i agree that letting them get out of sync is undesirable), then i'd go back to one of the two suggestions i made in https://github.com/sclorg/s2i-python-container/issues/324#issuecomment-657607470

[hhorak]

My preference goes to having the official OpenShift doc more hand-wavy (include basic usage, that does not change) and point to the Red Hat Catalog where the full doc should be available (not to github).

[frenzymadness]

Closing. We don't use docker hub anymore and we are not responsible for OpenShift documentation.