docs icon indicating copy to clipboard operation
docs copied to clipboard
verified publisher icon docker-library

Support named groups in "Supported tags"

Open md5 opened this issue 10 years ago • 12 comments

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:

md5 avatar Mar 13 '15 03:03 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).

md5 avatar Mar 13 '15 03:03 md5

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?

tianon avatar Mar 13 '15 03:03 tianon

Just ignore the fact that I mentioned # supported: false :hear_no_evil: :see_no_evil: :speak_no_evil:

md5 avatar Mar 13 '15 04:03 md5

:+1: 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?

yosifkit avatar Mar 13 '15 21:03 yosifkit

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)
  - ...

md5 avatar Mar 13 '15 21:03 md5

I'm also :+1: 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 avatar Mar 13 '15 21:03 md5

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

md5 avatar Mar 13 '15 21:03 md5

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?

tianon avatar Mar 13 '15 21:03 tianon

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 avatar Mar 13 '15 23:03 md5

FYI, I put in a PR over in the jenkins repo to output their stackbrew library file with the # group: ... comments: https://github.com/cloudbees/jenkins-ci.org-docker/pull/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.

md5 avatar Mar 16 '15 19:03 md5

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 (https://github.com/docker-library/official-images/issues/2289).

yosifkit avatar Mar 04 '17 02:03 yosifkit

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. :disappointed:

tianon avatar Mar 06 '17 18:03 tianon