Support named groups in "Supported tags"

[md5]

I was thinking today that it would be interesting to support named groups in the "Supported tags" lists in the README.md files.

For example, given a library file like this:

# maintainer: InfoSiftr <[email protected]> (@infosiftr)

# group: PHP 5.6
5.6.6-cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6
5.6-cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6
5-cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6
cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6
5.6.6: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6
5.6: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6
5: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6
latest: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6

5.6.6-apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/apache
5.6-apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/apache
5-apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/apache
apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/apache

5.6.6-fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/fpm
5.6-fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/fpm
5-fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/fpm
fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.6/fpm

# group: PHP 5.5
5.5.22-cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5
5.5-cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5
5.5.22: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5
5.5: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5

5.5.22-apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5/apache
5.5-apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5/apache

5.5.22-fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5/fpm
5.5-fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.5/fpm

# group: PHP 5.4
5.4.38-cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4
5.4-cli: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4
5.4.38: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4
5.4: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4

5.4.38-apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4/apache
5.4-apache: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4/apache

5.4.38-fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4/fpm
5.4-fpm: git://github.com/docker-library/php@1e07e9134490f53d24fbd23ee3521067c8ab2d29 5.4/fpm

You'd get the following YAML markup:

- **PHP 5.6**
  - [`5.6.6-cli`, `5.6-cli`, `5-cli`, `cli`, `5.6.6`, `5.6`, `5`, `latest` (*5.6/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.6/Dockerfile)
  - [`5.6.6-apache`, `5.6-apache`, `5-apache`, `apache` (*5.6/apache/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.6/apache/Dockerfile)
  - [`5.6.6-fpm`, `5.6-fpm`, `5-fpm`, `fpm` (*5.6/fpm/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.6/fpm/Dockerfile)
- **PHP 5.5**
  - [`5.5.22-cli`, `5.5-cli`, `5.5.22`, `5.5` (*5.5/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.5/Dockerfile)
  - [`5.5.22-apache`, `5.5-apache` (*5.5/apache/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.5/apache/Dockerfile)
  - [`5.5.22-fpm`, `5.5-fpm` (*5.5/fpm/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.5/fpm/Dockerfile)
- **PHP 5.4**
  - [`5.4.38-cli`, `5.4-cli`, `5.4.38`, `5.4` (*5.4/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.4/Dockerfile)
  - [`5.4.38-apache`, `5.4-apache` (*5.4/apache/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.4/apache/Dockerfile)
  - [`5.4.38-fpm`, `5.4-fpm` (*5.4/fpm/Dockerfile*)](https://github.com/docker-library/php/blob/1e07e9134490f53d24fbd23ee3521067c8ab2d29/5.4/fpm/Dockerfile)

And the following output:

• PHP 5.6
  • 5.6.6-cli, 5.6-cli, 5-cli, cli, 5.6.6, 5.6, 5, latest (5.6/Dockerfile)
  • 5.6.6-apache, 5.6-apache, 5-apache, apache (5.6/apache/Dockerfile)
  • 5.6.6-fpm, 5.6-fpm, 5-fpm, fpm (5.6/fpm/Dockerfile)
• PHP 5.5
  • 5.5.22-cli, 5.5-cli, 5.5.22, 5.5 (5.5/Dockerfile)
  • 5.5.22-apache, 5.5-apache (5.5/apache/Dockerfile)
  • 5.5.22-fpm, 5.5-fpm (5.5/fpm/Dockerfile)
• PHP 5.4
  • 5.4.38-cli, 5.4-cli, 5.4.38, 5.4 (5.4/Dockerfile)
  • 5.4.38-apache, 5.4-apache (5.4/apache/Dockerfile)
  • 5.4.38-fpm, 5.4-fpm (5.4/fpm/Dockerfile)

[md5]

The other thought I had was to expand this "pragma" idea beyond # maintainer: ... and # group: ... to include things like # supported: false (possibly helping alleviate the UX issue I mentioned in docker-library/official-images#544 by excluding all builds below that line from the README.md while still building them).

[tianon]

Liking the thoughts on grouping tags, but I'm actually pretty strongly -1 on a supported pragma; why even bother rebuilding an image if it's not supported?

[md5]

Just ignore the fact that I mentioned # supported: false 🙉 🙈 🙊

[yosifkit]

👍 on the idea of grouping tags. Do we just not care if they group some and not others or would that be more of a "linting" on our side before a PR merge to official-images? Maybe we should merge the docs repo into official-images to better entwine the two first?

[md5]

I think getting the generate-dockerfile-links-partial.sh script to work with the partially grouped case would be even trickier than just getting it to work with groups at all. That being said, I think that the markup can be intuitive and useful in some case (e.g. the Jenkins case):

- [`1.596.1`, `latest` (*1.596.1/Dockerfile*)](https://github.com/USER/REPO/blob/REF/1.596.1/Dockerfile)
- [`1.602`, `weekly` (*1.602/Dockerfile*)](https://github.com/USER/REPO/blob/REF/1.602/Dockerfile)
- **Other Releases**
  - [`1.601` (*1.601/Dockerfile*)](https://github.com/USER/REPO/blob/REF/1.601/Dockerfile)
  - ...

• 1.596.1, latest (1.596.1/Dockerfile)
• 1.602, weekly (1.602/Dockerfile)
• Other Releases
  • 1.601 (1.601/Dockerfile)
  • ...

[md5]

I'm also 👍 on somehow merging the official-images and docs workflows, but I'd probably like to see something in the source repos themselves. I think something like this is done for docs.docker.com.

[md5]

cf. https://github.com/docker/machine/blob/master/docs/mkdocs.yml

[tianon]

Yeah, but how do we know _where_ to get them from? Do we add a new pragma just for that? Also, how do we then verify at least a basic level of consistency across them?

[md5]

I think if you went with an approach like mkdocs.yml, you'd look for the file in a default location (e.g. docs/mkdocs.yml) and allow it to be overridden in the library file with a # docs: path/to/yml.

As for consistency, I think that bashbrew would need to be changed to build and test the docs just like it builds and tests the images currently, probably by just incorporating update.sh from this repo. I suspect this is similar to what would happen if you just merged official-images and docs and kept all the docs in the resulting repo.

[md5]

FYI, I put in a PR over in the jenkins repo to output their stackbrew library file with the # group: ... comments: jenkinsci/docker#71

Even if you guys don't end up wanting to use the # group: ... format, at least the changes I made there will make the preferred latest and weekly releases show up first in the current README.md output.

[yosifkit]

I'm not sure what applies anymore to the newer RFC-2822 based format. 😕 Maybe it'll be a little better when we do shared tags and manifest list tags (docker-library/official-images#2289).

[tianon]

Yeah, I think shared tags might help somewhat with the problem that's being discussed here, but not totally. PHP, for example, will still have a huge sprawl of tags that are a bit hard to sort through at a glance. 😞