docs: converge on a common set of example images
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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