#Discussion: Docs reviews workflow

1 messages · Page 1 of 1 (latest)

cunning marsh
#

@bright tangle @scarlet juniper @vagrant sinew

Here are some questions about current state:

  1. What is the current PR review flow for the docs site? I noticed the bot auto-pinging Gabriela.

  2. Where is this configured (not in CODEOWNERS)?

And starting the discussion for the future:
3. How do we want to approach it for the team so we don’t miss/double work?
Some ideas:

  • Make the bot mention all of us and people pick up reviews.
  • Assign doc areas of expertise (as we gain it).
  • Set up a Discord integration with #documentation and one of us picks it up and reacts with 👀.
bright tangle
#

the bot is not autopinging me. I only get notified on PRs that I have already commented on. Anyone can review any PR. Because reviewing contributions are high prio, I usually review every day, starting in the morning. Some days review is all I do. The bot will not ping you. You can just look at the PR queue and start reviewing it. I'm by far not the only one reviewing. if it says awaits-parent or approved it has been approved. If there are comments, people have already started a discussion. If it says parent-merged, the code PR has been merged and the docs PR needs to be reviewed so that it can be merged together with the code.

cunning marsh
#

Thanks!

So, how should we share this work? (whenever you want Rita and I to join in reviewing). Some ideas:

bright tangle
#

You can just review any PR you want to review.

cunning marsh
#

Thanks 🙂 I mean how we want to get organized as a team so we do it efficiently?

For example, if you start reviewing a PR, but only use the Github "submit review" feature, I think it's only visible to others after you submit it.
If someone else reviews and merges in the meantime, your work is wasted.

This happened to me here (through no fault of your own) - by the time I submitted the review, the PR was already merged.

next citrus
#

How do we want to approach it for the team so we don’t miss/double work?
So in core we rarely have this, also because the queue is huge so the chance is small you are reviewing the exact same at the exact same time. I am not sure if the frontend team has different approaches for this as there are less PRs there

#

Yea it happens sometimes, but too little to actually make a whole song and dance around it

cunning marsh
#

Thanks for the background! Yeah, I want us to start thinking about it so it's easier to scale.

I expect Rita and I to help increase the reviewing velocity, and what if we hire more people? 😅

normal estuary
#

As a suggestion, could we make use of Github assignments - so if you're about to review the PR, assign yourself so you can see who is looking at it?

next citrus
#

Downside of how we generally tackle PRs is that PRs are for anyone to pickup, so even if someone from the docs is on holiday for example, someone else is free to pick it up

#

Or if there's a new integration PR and someone from the docs team had a single comment and I see that it's solved and I have no further comments, then I'd also review it and merge it and done

cunning marsh
#

I think the key thing is not to make the tech writers blockers, but make sure these two things always happen:

  • You can always clearly tell whether a PR is being reviewed - so I recommend posting a comment saying "I'll review this" or assigning yourself (if you can)
  • A tech writer is made aware of a docs PR even if it's merged by someone else, so they can do a post-merge review if needed, and either ask for a follow-up from the original author or create it themselves.
scarlet juniper
#

Hi all! I completely agree with your first suggestion @cunning marsh, it will be very helpful. For organization, we can also think of using other labels, for PRs prioritization and identification of main topic.