Live Coding a Pull Request on the Terraform EKS Module's Documentation
I recently upgraded to the latest major release of the Terraform EKS module, got a little stuck and opened a PR to clarify things.
I’m a big fan of using Terraform and infrastructure as code in general. I was updating a pretty decently sized Terraform managed project to go from using version 17.x to 18.x and ran across an issue in their upgrade guide.
It wasn’t a bug or oversight on their end. It was mainly missing information
about what a specific output’s data type was supposed to be in the new 18.x
version. Specifically it was around wanting to use the new fargate_profiles
output which has a map of all of your Fargate profiles.
The video below goes over the motions of reviewing the issue I created, creating the PR, making the patch and submitting it. It focuses on the general topic of creating documentation pull requests in open source projects, it’s not very Terraform related.
# Live Coding Video
Timestamps
- 0:25 – This PR idea started by opening an issue
- 3:03 – I think upgrade guides should have extensive details and examples
- 5:49 – Starting things off by forking and cloning the repo
- 7:17 – Getting a feel for how their existing docs are
- 9:39 – Where should we add our new docs?
- 11:26 – Choosing a feature / problem based example instead of a reference
- 13:03 – Figuring out where to add the new use case example
- 15:29 – Adding the before / after for this IAM role policy example
- 18:51 – Adding more context on what each example does
- 21:07 – Reading things out loud and fixing a few grammar mistakes
- 22:36 – Double checking the existing docs for style hints
- 24:01 – Create a new branch and commit our work
- 26:36 – Starting to create the pull request
- 31:00 – Final call for reviewing your work before submitting
- 33:29 – Really creating the PR and then fixing a GitHub Action error
- 36:36 – Was it worth it? I think so, contributing back helps everyone out
References Links
- https://nickjanetakis.com/blog/when-to-use-long-word-or-short-letter-command-line-flags
- https://nickjanetakis.com/blog/writing-and-previewing-markdown-in-real-time-with-vim-8
- https://nickjanetakis.com/blog/find-and-replace-text-in-1-or-more-files-using-vim-fzf-and-ripgrep
- Dockerized web app examples on GitHub
- https://github.com/terraform-aws-modules/terraform-aws-eks/pull/1783
What was the last open source repo you contributed docs to? Let me know below.