NEWS file and container-versioning

[praiskup]

It would be nice to have some "NEWS" file saying what feature was added
and when. Similar for bugfixes. So far, we never incremented the version of image,
and the image had only the version of the base component (e.g. 9.6, then we
switched to version=1).

• the NEWS file should be available in git root directory
• but also added to /NEWS path, so anyone can do docker run ... cat /NEWS
• the version of the container should be printed out by usage
• I'm not sure we need docker tag here
• major version should be incremented if some incompatible change is done
• minor version should be incremented right after release (every 6 weeks so far)
• we should tag git commit before any version change

[pkubatrh]

+1

Additionally it would be awesome if the NEWS file included any Bugzilla bugs fixed in the release.

[omron93]

(I'm taking this issue as general discussion about all our images. If it wasn't meant so, then I'm sorry. Development of postgresql image is one of "the most active" ones, so usage of NEWS file could be little bit different from a less active ones.)

+1 for NEWS file and for adding fixed bugzillas in it

the version of the container should be printed out by usage
major version should be incremented if some incompatible change is done
minor version should be incremented right after release (every 6 weeks so far)

About a version I'm not so sure. Is this related only to CentOS images or also RHEL images should be affected?
CentOS images aren't rebuild together. They are built right after git change (or base image change). And also some images aren't changed so much. So I would avoid any "periodical" changes of version (~ minor version/time of rebuild for new base image).

Also one difference to RHEL images is that centos images contain git commit hash of sources the image was built from. So IMHO it's equal "way" how identify image and to see what changed in upstream.

I'm not sure we need docker tag here

Without docker tag, I personally can't see any advantage of versioning. You can identify image sources anyway.
Tagging images with versions as a tag could provide "nicer/simpler" (incremental) way how to be able to intentionally use older images from Docker Hub. (different question - is this what we want?)

What about changing version for uncompatible changes (centos images are currently tagged using version, so both versions would be available) and use date in NEWS (and add there also other bigger changes - RFE,...)

To note: there is already "NEWS file for images" card in our trello board - by @hhorak

In order to be able to say what changed in the particular rebuild, we might start maintaining Changes files that will be updated together with a PR, for every reasonable big change.

Ideally, the format should be machine-readable friendly, so we can convert it automatically to a summary that includes changes for all images that are part of the rebuild.

Maybe YAML might work for this?

2017-11-23:
- Some change
  link to github discussion or any other multi-line description
  Nathan Scott <nathans@redhat.com>
- Another change
  some other description

2017-10-23 Nathan Scott <nathans@redhat.com>:
- Some change
  link to github discussion or any other multi-line description

2017-10-03:
- Another change
  some other description

[praiskup]

About a version I'm not so sure. Is this related only to CentOS images or also RHEL images should be affected?
CentOS images aren't rebuild together. They are built right after git change (or base image change). And also some images aren't changed so much. So I would avoid any "periodical" changes of version (~ minor version/time of rebuild for new base image).

Well, the question is whether we shouldn't do something about it -- namely, whether we shouldn't delay the release the new version of CentOS images till RHEL images are at least ready for release.

The point is that we should somehow pair the released centos images with released rhel images;
if we bump the (minor) version, you'll see that centos image v1.1 is corresponding to rhel image v1.1

Also note that you have to be able to reference concrete (even minor) version in the NEWS file.

What about changing version for uncompatible changes (centos images are currently tagged using version, so both versions would be available) and use date in NEWS (and add there also other bigger changes - RFE,...)

Yes, incompatible changes usually lead to major version bump.

[omron93]

Well, the question is whether we shouldn't do something about it -- namely, whether we shouldn't delay the release the new version of CentOS images till RHEL images are at least ready for release.

Hard to say what users want more - quicker updates or "verified" testing? @hhorak Do you have any feedback from (openshift) users?

The point is that we should somehow pair the released centos images with released rhel images;
if we bump the (minor) version, you'll see that centos image v1.1 is corresponding to rhel image v1.1

Well, this is somehow connected to question above.

RHEL images includes build date. And we definitely should add this label to Centos images too (there is such label, but is inherited from centos base image).
And build date allows comparing of rhel/centos images...

Also note that you have to be able to reference concrete (even minor) version in the NEWS file.

This could be allowed by using time - compare date of the change in NEWS and build date.

Well, generally containers are released really often. And personally I would like to avoid changing sources for every build. (for average image, image is (re)built more often than changed)
That's also the reason I like labels. They can be added to the image in built time, without need to touch sources and commit changes back to github.

[praiskup]

Well, generally containers are released really often. And personally I would like to avoid changing sources for every build.

I'm not sure I understand this. What implies that we should change sources for every build?

[omron93]

I'm not sure I understand this. What implies that we should change sources for every build?

Build only when base image is released (same as for RHEL now) -> bump minor version number for that release/build -> show version in usage -> inside image labels aren't available (so version have to be stored/changed in image sources ~ probably Dockerfile)

[praiskup]

Well, if there's no other change (== no new NEWS entry) I don't think we have to bump the version.

[omron93]

So minor version should be increased by every commit with NEWS entry?

Or it was meant that not for every build but for every build where sources changed? If so, I don't see a difference. So edit: "And personally I would like to avoid changing sources for builds." (~ push changes in minor version into master right before build of image with changes)

[praiskup]

Typically, NEWS file looks like this or this. People look there and see what changed and when. Referencing point in "time" (dates) is probably useless, you need to have (some) versioning.

So minor version should be increased by every commit with NEWS entry?

Not really. Minor version should be bumped if something is worth having added to NEWS entry, and we already released all the previous set of changes.

[omron93]

Not really. Minor version should be bumped if something is worth having added to NEWS entry, and we already released all the previous set of changes.

So first commit changing NEWS after image was build, right? Which assumes that centos images are build only for new base image (same as RHEL now)... So frequency of centos builds have to be decided IMHO.

[praiskup]

On Thursday, April 5, 2018 12:03:03 PM CEST Marek Skalický wrote: > Not really. Minor version should be bumped if something is worth having added to NEWS entry, and we already released all the previous set of changes. So first commit changing NEWS after image was build, right?

I'd say so.

Which assumes that centos images are build only for new base image (same as RHEL now)... So frequency of centos builds have to be decided IMHO.

Yes, basically we could just ship "not-yet-rhel-released" minor versions for CentOS to avoid additional burden initially, since we don't have to care that much. In (maybe rather far) future, I think it will be anyway necessary to maintain some "release" process (e.g. given by release tags in master branch history), and release the images manually since releasing from git snapshots is a bit risky. But I don't think _now_ is the right time to bother with that. Well, I don't want to sound too definitive ... we are just discussing, and I'm just presenting what I personally feel is natural if we were about to maintain usable NEWS file.

[omron93]

Well, I don't want to sound too definitive ... we are just discussing, and I'm just presenting what I personally feel is natural if we were about to maintain usable NEWS file.

For me this was discussion too and I didn't want to discourage you from this effort. All ways are doable and I'm not strongly against any one. I only imagined a process of enforcing maintainers to change version in right time, don't forget it,... and I don't see any "cheap" way. Sure, I can be missing something...

[praiskup]

On Thursday, April 5, 2018 12:41:30 PM CEST Marek Skalický wrote: I only imagined a process of enforcing maintainers to change version in right time, don't forget it, ...

Well, we could speak about "recomendations" rather than enforcements. It's not my intention to setup some formal process, I rather think about some best-effort and maybe opt-in process.

and I don't see any "cheap" way. Sure, I can be missing something...

No doubts, manual maintenance of NEWS file is never for free. Whether it is cheap or not... it depends. It shouldn't be very much "expensive" neither, and the convenience of users should outweight the additional care we'd have to pay.

[pkubatrh]

As for the major.minor versioning - I would be a bit scared about the result of changing to this, since currently (afaict) the images are tagged using the version label. So even a minor version bump would create a new tag. So users consuming say postgresql10:1 would be unable to get postgresql10:1.Y (and 1.Y+1 and so on) without making modifications.

I guess this could be changed somewhere in the push state (to tag 1.Y as 1?) but I am not sure if it is worthwhile to do just to be able to use the versioning in the NEWS file...

On the other hand I do not think a NEWS file with just time stamps is really useful. The build date labels will not imply that changes that got upstream before that date are inside the image - the image might have been built a few days after a sync has been done (for rhel), or even a few weeks (CVE rebuild case).

[praiskup]

I guess this could be changed somewhere in the push state (to tag 1.Y as 1?)

Good point. Right, that's what would be needed (I originally designed the versioning this way in https://github.com/devexp-db/cont-postgresql, docker pull -a praiskup/postgresql). Btw., this clearly means that any version bump (major or minor) is to some extent insecure, because if people were running against them -- they would loose the updates after the bump. edit: I mean even with the current status. So we should basically never bump the version, right?

[pkubatrh]

Btw., this clearly means that any version bump (major or minor) is to some extent insecure, because if people were running against them -- they would loose the updates after the bump.

Well if we use the version bump for breaking changes right now I think it is a good idea for people not consume it (the new version) by default. But that would not be the case with minor version updates.

[praiskup]

Well if we use the version bump for breaking changes right now I think it is a good idea for people not consume it (the new version) by default.

Sticking with concrete tag version isn't good idea at all, because - if we ever bumped the version - the old version would never be updated more for security issues. So in turn it means that we should never bump the version... or we should stop tagging the images because that is a bad idea.

And, unfortunately, I don't think our current workflow allows breaking changes... :-)

[pkubatrh]

@phracek to take a look at generating NEWS file from commits during PRs as a optional step. Expecting the PR creator to modify the NEWS file accordingly.