Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

microsoft/dotnet Docker Hub README adopts segmented OS/Arch style #27

richlander opened this issue Aug 14, 2017 · 1 comment

microsoft/dotnet Docker Hub README adopts segmented OS/Arch style #27

richlander opened this issue Aug 14, 2017 · 1 comment


Copy link

@richlander richlander commented Aug 14, 2017

microsoft/dotnet Docker Hub README adopts segmented OS/Arch style

The Docker Hub README style used by microsoft/dotnet and microsoft/dotnet-nightly has been updated to use a new model that is segmented by OS and chip architecture.

You can see an example of the new style in the following image.

screen shot 2017-08-13 at 10 44 34 pm


You can share your thoughts on this change or see what others are saying at:


The microsoft/dotnet repo (and by extension microsoft/dotnet-nightly) has been steadily growing with each release of .NET Core and also of the underlying operating systems that we support. We wanted to present simple-to-read tag lists. As the repo has grown, the tag list has gotten longer and more complicated.

The addition of arm32v7 to the repo caused us to spend considerable time thinking about repo organization generally. We looked at other approaches and also talked to Docker employees about their long-term plans for arm32v7 in particular.

We considered various options:

  • Split the repo by architecture (this seemed to match what Debian and other official repos were doing). See debian and arm32v7/debian. Note how the Debian GitHub repo is structured, branching by architecture.
  • Split the repo by SDK and Runtime. We've discussed this multiple times but we believe that discoverability would be a significant challenge. Also, other peer development platforms do not segment on the SDK/Runtime boundary.
  • Stay the course on the repo structure, but adopt a new (hopefully better) approach for the tag list.

There are three main reasons that we adopted a new README style:

  • Multi-arch tags are visually awkward when you have multiple versions of an operating system for a given tag type. For example, the dotnet repo offers both Debian 8 and 9 variants of the 2-sdk tag. Only one of them can participate in the multi-arch tag while the other variant (in this case Debian 8) is only available with the longer tag name: 2.0.0-sdk-jessie. The way the bullets in the tag list compose looks odd, as you can see in the following image. It also doesn't communicate the relationship between tags well. screen shot 2017-08-13 at 11 14 22 pm
  • A multi-arch-first tag list works well when all OSes offer the same image types, but is poor at showing differences when they don't. The .NET Core offering for arm32v7 is quite limited currently. We wanted to make that obvious.
  • We believe that most users look at the README with a specific OS in mind. We thought that it was best to cater to that, providing a simplified view for a given OS.

The downside is that this README style is unique (AFAIK). We've never tried to be novel with our Docker offering, but fit into existing conventions. This is our first significant departure from Docker norms. There is a lot changing in the Docker space, with multi-arch and arm32v7 being top of the list (as it relates to this topic). As a result, we thought that now was a good time for experimentation based on the conclusion that the existing README style no longer scales to our needs. Our conversations with Docker employees also led us to believe that there are no good established answers to these challenges.

Please give us your feedback @ dotnet/dotnet-docker #275.

@dotnet dotnet locked and limited conversation to collaborators Aug 14, 2017
@richlander richlander closed this Nov 7, 2017
Copy link

@terrajobst terrajobst commented Nov 10, 2017

Reopening according to process.

@terrajobst terrajobst reopened this Nov 10, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
You can’t perform that action at this time.