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

[richlander]

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.

Also published at dotnet/announcements #27.

Details

• dotnet/dotnet-docker-nightly #328
• moby/moby #33759

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