search

smebberson / docker-alpine

Docker containers running Alpine Linux and s6 for process management. Solid, reliable containers.
MIT License
596 stars 186 forks source link

Roadmap and changelog #37

Open matthewvalimaki opened 8 years ago

matthewvalimaki commented 8 years ago

References #36.

Roadmap See Wikipedia explanation.

Purpose of a roadmap is to set goals and expectations. Roadmap sets focus and drives excitement. Roadmap does not dictate every single change but rather lists known immediate upcoming changes and tries to define more distant changes - a wishlist in its simplest form. After a release roadmap should almost from word to word be in changelog.

Current state of docker-alpine project is that there is no roadmap. Releases are sporadic, which is fine and understandable considering this is a community project, but more problematic is the what is needed for a release to happen. While a release could happen, especially with automation, after every single change to set goals and expectations might be preferable. Having a roadmap should also alleviate pressure from release master as there are now more clear definition of when to release.

I propose GitHub milestones feature to be used. All issues are to be triaged and then moved to a milestone, comments requested or closed. This process should be as lightweight and quick as possible.

Changelog Example that I like: https://github.com/hashicorp/consul/blob/master/CHANGELOG.md.

I propose a simple changelog based on roadmap (or more specifically milestones). If changes are issues and issues have meaningful context (so far they have) then I do not see a point to write again what was changed, why etc.

Note: docker-alpine project due to it's multiple release numbers (one per image) does pose a challenge. In order to simply versioning moving to one release number for all, even if no change is done, might be in order. Then in changelog we could just note

NO CHANGE LIST:
alpine-nginx-nodejs
alpine-nginx

I do acknowledge that doing a release with no changes is curious thing, but I believe it simplifying things outweights the negative.

smebberson commented 8 years ago

@matthewvalimaki, I'm definitely down with the Roadmap. I think that would be a great idea.

It would be good to discuss releases (on Docker Hub) a little more. They're quite time consuming and manual at the moment. Docker Hub functionality is quite limited especially when it comes to automated repositories. It would be great to work out a way to streamline lines. I think I'll document a seperate issue to discuss this specifically.

Regarding the CHANGELOG: yeah, that's a tricky one too. Do you like the current versioning as it is explained here https://github.com/smebberson/docker-alpine#versioning? I'll admit that new people coming into the project could find it confusing. Take for example the Node.js containers, they update frequently. And once I go through and update the base images all node.js 4.x releases and node.js 5.x releases won't be on the same alpine-nodejs X.x path (if that makes any sense). Maybe the versioning needs to be rethought? Maybe we keep the version numbers as they are for each image, but move away from versioning for the entire repository. Eric Elliot explains it better than I can. More food for thought...

smebberson commented 8 years ago

I've created #38 to discuss testing and automated releases.

matthewvalimaki commented 8 years ago

@smebberson thank you for the thoughtful response. Clearly you've given this some thought. I'll think about this more and come back to it.

smebberson commented 8 years ago

@matthewvalimaki, another idea here is to rename each VERSIONS.md file to CHANGELOG.md (that should have been the case in the version place). The CHANGELOG would list the version number of the image itself and what has changed, just like a traditional changelog. Then in the VERSIONS.md file we could create page that simplifies upgrade paths for people - like I was aiming to do with https://github.com/smebberson/docker-alpine/blob/master/alpine-consul-nodejs/NODEJS.md (so information is grouped by the primary software version number, i.e. Node.js or Nginx).