Determine how to use CODEOWNERS for Source Code
Problem statement
Marcin and Amy are now splitting the Source Code documentation, but the split has been tough to enforce because - unlike Distribution - no clear delineation of features exists that we can use for splitting purposes. Right now, we are both listed as CODEOWNERS for all pages in the Source Code docset. That's a good start, but the pings are not divided between us, but instead duplicated.
So how do we split this docset apart so we're truly splitting the incoming pings, and how do we handle the downstream ramifications of these changes?
Links you'll need
- The contents of
lib/tasks/gitlab/tw/codeowners.rake
- are used with these instructions https://docs.gitlab.com/ee/development/documentation/#batch-updates-for-tw-metadata
- to update this file https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/CODEOWNERS
Possible approaches
-
Add extra code to the Rake task. A possible approach would be the code equivalent of "pages marked
Source Code
in directory X go to Amy, and everything else to Marcin."-
👍🏻 done right, it could be reproducible for other groups. -
👍🏻 it preserves a single name for the group, which is likely needed for downstream tooling -
👎🏼 We'd need to get help from someone outside of Technical Writing; I don't know if any of us can write this ourselves. I know I can't.
-
-
Use a different name for the group in individual files. In our
*.md
files, we declare a stage name and a group name. We could potentially sidestep the need for additional code, if we give Marcin's files one group name (group: Source Code - Marcin
maybe?) and Amy's another.-
👍🏻 Lightweight, and doesn't require external coding help. -
👍🏻 Reproducible for other groups. -
❓ Potential unknown ramifications to downstream tooling. I think the queries that build the Content Audit spreadsheet rely on group names. It would change calculations, but that's not necessarily bad - it might help us see if we've divided content responsibilities fairly.
-
As I've written up these instructions, I'm realizing I like option 2 a lot. It has fewer moving parts, and doesn't require us to ask for help. Groups change / morph / split / join all the time. It might be that our other tooling is already set up to adapt to group name changes, and it's no big deal. However, the right thing to do is ask first. I'll tag the people I think I need to check with.