Never Underestimate Making Pull Requests to Update Documentation
Even the smallest contributes are often welcome and they could lead to internal discussions that promote change.
Quick Jump: Demo Video
A few days ago I was updating my Ansible Docker role.
Docker used to support stable, test, edge and nightly release channels where the further you go right, the more bleeding edge you get at potentially the cost of stability.
My role defaults to stable but it had documentation to mention that you can set other channels if you want. I decided to check the script at https://get.docker.com/ to see if those channels were still supported so I can update accordingly.
Nope, it had these comments in the script:
# * stable
# * test
# * edge (deprecated)
# * nightly (unmaintained)
Note: get.docker.com has been updated since I added a PR so the live copy no longer shows it as unmaintained, it shows it as deprecated.
However, both edge and nightly had the same warning being echo‘d:
DEPRECATED: the $CHANNEL channel has been deprecated and is no longer supported by this script.
So there was a discrepancy here. Was nightly deprecated or unmaintained? As a Docker Captain I asked Docker’s engineers and received an answer very quickly.
Nightly was supposed to replace edge but they decided not to support it after realizing the type of engineering maintenance that would have been needed to keep it up.
They think it’s ok to officially deprecate it and suggested I make a PR so I created https://github.com/docker/docker-install/pull/377 which got merged shortly afterwards.
One takeaway here is this started as adjusting 1 comment but it got Docker to evaluate something and make an official decision based on something they made a while back. You never know what someone might think about or change after making a tiny suggestion.
Demo Video
Timestamps
- 0:19 – Configuring Docker’s release channel with Ansible
- 1:04 – Checking Docker’s supported channels
- 2:18 – Asking Docker for clarification
- 2:52 – Going over the small pull request to Docker’s install script
- 3:56 – It caused Docker to think about a previous decision
What was the last PR you made that was documentation related? Let me know below.