What is the best way to put on a repository for a docker image with multiple tags? I've seen a lot of repositories with Docker images and I think (correct me if my guessing is wrong) that the projects that handle a docker image with multiple tags can be grouped into three groups: 


Dockerfiles with different names in the same directory.
Dockerfiles with the same name (i.e. "Dockerfile") in different directories.
Dockerfiles with the same name (i.e. "Dockerfile") in different branches.


I've looked at the Docker documentation page but there are no suggestions on how one should manage multiple tag images. I'm not looking for a subjective answer. Of course, any advice will be appreciated but what I want is to know the pros and cons of each of the three possibilities.

Of course, there is the possibility that I've understood nothing of how docker images should be deployed. In this unfortunate case, please be merciful and point me in the right direction.



Case study

I wanted to pose a general question but I realized that maybe it was too broad. For this reason, I explain here what is my case hoping that could help a bit more what I wanted to achieve and what I've done now (this question is about only a part of what I wanted to achieve). 

What I want is to develop a docker hub automated build linked to a Git Hub repository. The images are about LaTeX on Ubuntu. The first build, tagged base, starts from Ubuntu 18.04 and comes with texlive-base. Another build, tagged full, starts from the build tagged base and comes with texlive-full. Another two builds, tagged develop-base and develop-full, will start from the respectively builds without 'develop' and will come with writing and visualization tools. All the builds will probably have some semantic versioning system. 

What I've done right now is implement base and full through two different Docker files into two different directories in the same Git Hub repository. Whenever a tag base or full is created/moved, the corresponding build is triggered. This implementation has a problem: if I move the tag base, the image base is correctly built but all the images that depend on it are not built again and I have to manually trigger them. What I've thought is to have a branch for each tagged image (with the corresponding automated builds triggered at each new push on that branch) and a tag system to keep track of the version number (with the corresponding automated builds triggered at each new tag). The tags will be base, full, develop-base, etc. for each latest version and with semantic versioning for each version, including the latest, i.e. 1.0-base, 2.3-full, 1.3.1-develop-base, ecc. In the latter case, the automated build triggering will probably have to handle regular expression to automatically label the images with a version number.

I realize that my question isn't very related to what I wanted to achieve but I want to learn to walk before trying to run. Thus, I want to understand when and why one should choose one way or the other to put on a docker hub repository with several images and which are those ways. The project of LaTeX images itself, that maybe you could think that is very naive, is to deeply understand the way docker, docker hub, docker cloud, docker compose, ecc. work.
If you think of the Dockerfile as a kind of "bill of materials" for your containers, then there is the following consideration:


container environments are mostly same - you can use many Dockerfiles in same folder, or even just one Dockerfile with parametrized builds
container environments are or might divert in terms of further "local assembly parts" configuration files, scripts etc., then you are better off with using separate folders.


Branching has rather to do with developing versions, or also independent features which then should be anyway merged together. See Git flow on this topic.

As a reference project laoyut, check for example the GitHub project linked from Tomcat Docker Hub site. Here you find different folders, even with single Dockerfiles.

See also this TeX-Docker distro:


https://hub.docker.com/r/raabf/texstudio-versions/


Side note: strange enough there is no "official" Docker distro for TeX, while many other well established open source communities have this library entry.