As the team grows and changes, can we make it easier for our engineers to assign/ping an appropriate technical writer for their MRs?
Proposal
I think we should look into expanding the Danger Roulette message to contain a line suggesting a technical writer. It can be as simple as choosing based on DevOps stage:
Are you including docs in this MR? If so, feel free to ping {technical writer}(chosen due to {devops::stagename} label) when the docs are ready for review.You may choose a different technical writer if desired, or if {technical writer} is OOO.
A future iteration could enable the ability to divide the work between is the current expert, and a TW new to the group/stage. Imagine 80% of the time the expert is suggested, 20% of the time the "apprentice" is suggested. As the new TW gets up to speed, it can go to 50/50, then 100% when the new TW is suitably up to speed, as an expanded idea.
There is no need to be strict about this. The Engineers seem to be making good use of the Danger Roulette, and they should be adding docs with feature changes already, so letting them know ALL the suggested reviewers at the same time and in the same place seems to make sense.
Designs
Child items
...
Show closed items
Linked items
0
Link issues together to show that they're related or that one is blocking others.
Learn more.
@gl-docsteam As discussed in our meeting, here is the issue. It probably isn't all that hard, but it might be best to ask someone knowledgable with Danger to help out if possible, if we decide to go this route.
Thanks @marcel.amirault. Automation is good. Question: what problem are we trying to solve? Is it hard to ping the correct technical writer now?
The process we have now is, we manage what gets sent to the "apprentice" and, when we feel it's time, they take 100% of the reviews. For time, they are then coached. They after that, they are a maintainer.
@marcel.amirault we used to have this bot to do this for us, we removed bc it was confusing. We currently have tech writers assigned by stage/group, so this doesn't make sense.
The "apprenticing" aspect would just have been a beneficial side effect, but not the primary goal. The idea is just to continue treating our "docs as code" as much as possible, and make the docs review appear in the comments the same as the code reviews. It would direct new engineers to the correct person immediately, and would also help anyone moving to a different team. The message would also be able to make it clear that they could assign both the code review and docs review at the same time, if possible, to speed up the overall review time.
I know that this is something people will learn, and they will learn who their "go to" technical writer is, it just seems like we have a tool that could help enforce this more precisely.
It would also be interesting to start using it for Community Contributions, as a normal roulette, to divide up the initial review/triage.
Just putting these ideas out for discussion, not saying it's critically important.
I'm wondering if we refine that and make reviews for merge request labeled a particular way fully rouletted, if possible? You'd end up with a table like the following in those circumstances:
That entry would join the normal frontend and backend rows etc. As with any roulette suggestion, they can be disregarded. You can see it in action over at gitlab-development-kit (docs reviews are always rouletted in that project): gitlab-development-kit!2234 (comment 716390876).
@eread It actually makes even more sense to me now than when I originally created the issue. I feel like this would actually be quite a small change overall, because as you said, Danger already leaves a message saying that a docs review is needed, for example: !73520 (comment 720594708)
So all we would do is improve that message with a potential TW that could address the issue. And if it's the wrong person, they can reassign (that's if the author even picks the person suggested by roulette).
It would also make it easier to to redirect reviews away from TWs with , so that's another benefit.
This would hopefully help TWs with by automatically triaging away from them, rather than them having to ask for help.
I'm in favor of this, but we need to be more careful and avoid introducing bugs. For example, GitLab bot still seems to be pretty buggy and generates a lot of noise and false positives.
Availability is currently pulled from Slack and GitLab statuses:
A team member is considered to be on leave if the status contains OOO / PTO / Parental leave
, , , or emojis: The team member is considered to be on leave
emoji: A team member is considered to be at capacity and will not be considered for reviews
emoji: A team member is considered to be in focus mode (focusing on their team's work) and therefore excluded from reviewer roulette
emoji: A team member is considered to be "hungry" (longing for reviews) and will be chosen more often for reviewer roulette
emoji: A team member is considered to be "reduced capacity" and in cases where there are
other reviewers available, will be chosen less often for reviewer roulette
I'm definitely in favour of this, though I think feature docs work should go only to that stage/group's assigned TW. As others have said, we can always redirect a review for whatever reason.
A question: how does this play with CODEOWNERS? Would you still get a roulette suggestion if the file already has an owner in CODEOWNERS?
@kpaizee I don't think CODEOWNERS comes into play. I'm pretty sure the data is sourced the same as for: https://about.gitlab.com/handbook/engineering/projects/. The reason I set Reviewer to "unavailable" in my example above is that we don't have any non-maintainer writers.
@msedlakjakubowski thanks for posting that here. I hadn't realized was available.
The great thing about , , and is that folks can asynchronously specify they're available, extra available, a bit unavailable, or completely unavailable, without having to Slack their team.
@kpaizee Was your question based on the behavior of community contributions, where we get pinged on them based on CODEOWNERS setting? I think that might be from:
@eread Yes, that's a more specific answer to my vague question I was wondering if two different writers could be mentioned on the same MR (one getting pinged by the bot based on CODEOWNERS and the other suggested by the roulette). But even so, we could refine over time as we discover what happens.
@kpaizee There are a couple of theoretical possibilities (not sure if supported with current tooling) for Community contribution, I guess:
Ping based on CODEOWNERS as now. Don't use roulette.
Ping based roulette instead. The message would be something like Hi @kpaizee, you've been selected by Danger to review this ~"documentation" Merge Request.
The advantage of using roulette is that regardless of CODEOWNERship, it takes PTO and review load into account.