docker / docker/cli

docs: converge on a common set of example images

Open
#4,902 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

kind/docs
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

Description

Possibly low-hanging fruit, and perhaps more things to discuss here; we should make a pass at converging on what images to use in our examples, so that users don’t have to pull different ones when trying new examples. Somewhat leaning towards a combination of ubuntu and alpine;

git grep ' debian' **/*.md | wc -l
18
git grep ' ubuntu' **/*.md | wc -l
140
git grep ' alpine' **/*.md | wc -l
45
git grep ' busybox' **/*.md | wc -l
147
Why alpine over busybox?

busybox is nice and small, but doesn't have a package manager, so any example using that is effectively "end of the line. that's it. if you want to expand this example to something more useful, you don't have many options.", so alpine is a nice in between; slightly larger, but still small. alpine is also used as base-image for various variants of official images (e.g. nginx:alpine), so things you learn using it can still be applied to those if the user wants to create small images.

alpine vs ubuntu

Using alpine vs ubuntu depends a bit. alpine is definitely smaller, so for "one-off" examples is nicer than ubuntu. In some cases, alpine:latest may be slightly more clear on "for illustration purposes". Lastly; ubuntu:latest strictly speaking doesn't match our "best practices" (:latest being a "moving" tag). Admitted, perhaps not the most horrible thing to keep things simple, and because ubuntu:latest will always be latest LTS, so not completely "random", and still reasonably stable).

Many examples could probably work with alpine, but there’s something to be said for keeping ubuntu as well, as more people are familiar with working with ubuntu than alpine, but that would depend on the example I guess (i.e., do we expect them to use the example as a starting point for things they’re doing? and in that case, perhaps expect ubuntu(ish)?)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running the issue's git grep commands across the Markdown examples in **/*.md and compare the current Debian, Ubuntu, Alpine, and BusyBox usage. Review the resulting examples and the discussion before deciding on a common image set; done means the examples consistently use the agreed images and still work as documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.