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.
Quick Jump: Live Coding Video
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.