Document tw::codeowners rake task
In gitlab!77715 (merged), I worked with some engineers to build an MVC for generating bulk updates to the Technical Writing portion of the CODEOWNERS file. However, the command is definitely MVC (hi @sarahgerman!) and requires some manual steps that we should document / iterate on to improve.
Why did we need the rake task?
- New pages get added all the time, and we rarely remember to add a CODEOWNERS entry.
- We can't trust that deeper subdirectories in the tree contain files belonging to just one group, so we often have to set CODEOWNERS on a file-by-file basis. For example,
doc/user/project/merge_requests
- which you'd really think would be a slam-dunk for groupcode review - also contains pages for ~"group::pipeline insights", groupsource code, and groupstatic analysis. - Our writers maintain docs for multiple groups. When one of those groups is transferred (temporarily or permanently) to another writer, it can be tough to determine what pages need a CODEOWNERS update, and several docsets are big enough that manual updates would take time.
What is the rake task?
bundle exec rake tw::codeowners
What instructions did Amy have at the start of this issue?
Updating the rake task when new groups are added
- Wholly TBD here.
(Note: pages without an assigned group do not receive a CODEOWNERS entry.)
Running the rake task
- Make any changes needed in
lib/tasks/gitlab/tw/codeowners.rake
(add / remove groups, update assignments). Create a separate MR for these changes, as they're considered backend changes with a long pipeline. - Run the task from the root directory of the
gitlab
repository, and dump the output to a file, like this:bundle exec rake tw:codeowners > ~/Desktop/updates.md
- Open the file you just created and clean it up.
- Bulk change
./
to/
- Use the command palette to sort the output in ascending order.
- Bulk change
- In the
gitlab
repo, edit.gitlab/CODEOWNERS
- Remove the docs-related lines after the line
^[Documentation Pages]
and replace it with your changes. Important: our section is NOT the last section of the file! - The undocumented part: look for directories that contain files all owned by a single group, and create a line that assigns all files in that directory to a group.
Now for the dodgy stuff
- The output is a raw dump of all files. To reduce the size of our CODEOWNERS entries, look for directories that contain files all owned by a single group, and create a line that assigns all files in that directory to a group. Creating a script that condenses down these unneeded lines without human intervention was well past the MVC we had time to create, but would help tremendously in the future.
- Review a diff of the output. Be suspicious if multiple files for the same user / group are removed, and this user / group is not the focus of your change. In the past, I've seen this happen when a group is renamed / removed / otherwise no longer matches the exact name of the group listed in the array in
lib/tasks/gitlab/tw/codeowners.rake
. A smarter future iteration would go pull a list of groups from … somewhere. - Use common sense. If the diff of the output doesn't look like what you expect, compare 1) the metadata for the pages whose CODEOWNERS entry changed and 2) the array in the
lib/tasks/gitlab/tw/codeowners.rake
. Misspellings can be subtle;Authentication and Authorization
vsAuthentication & Authorization
for example!
Related issues
These issues and MRs describe the evolution of the CODEOWNERS project for the Technical Writing team, from the initial idea through multiple (!) iterations to a finished product. These links may have been added significantly after this issue or merge request was closed, so they may describe parts of the process before or after this work.
- Related to Create rake task for docs CODEOWNERS (gitlab!77715 - merged) where Amy had an idea
- Related to Update CODEOWNERS to include TW assignments for... (gitlab!77606 - merged) where we asked for the raw output of the Rake task to be added into the CODEOWNERS file. This rake task would give the TW team a way to periodically generate a full list of owned pages.
- Related to Expand CODEOWNERS with more documentation DRIs (gitlab#349587 - closed) where Marcel noted many pages needed a DRI declared
- Related to Update CODEOWNERS to include TW assignments for... (gitlab!77606 - merged) where we started manually shortening the results
- Related to Refine how to run batch updates for the CODEOWN... (#668 - closed) where we started figuring out how to run batch updates
- Related to Codeowners: Assign TW with more than 50% page o... (gitlab#375783 - closed) where we started automating the process of shortening and condensing the results
- Related to Document tw::codeowners rake task (#598 - closed) where we documented the task
- Related to Create custom stage / group for tutorials section (#672 - closed) where we had to find alternate assignments for part of the docset that is owned, but not by a stage/group
- Related to Release Post 15.7 MVP Nominations (gitlab-com/www-gitlab-com#14283 - closed) where Niklas was nominated as MVP for the months of iteration needed to bring this script to a full, workable state
Edited by Amy Qualls