Update welcome message from OSPR bot with info and checklist for authors

itsjeyd commented 5 months ago

Story

"As an author of an OSPR (open source pull request), I want to get a useful welcome message after posting my PR so that:

I know where to look for relevant information about the OSPR process if/when I need it.
I know which steps I need to complete to get my PR ready for engineering review.
(maintained repos only) I know who to ping for engineering review."

Full description

One important aspect of reducing time-to-merge for OSPRs is to empower PR authors to manage more parts of the OSPR process themselves.

For that, they'll need:

Easy access to information about the OSPR process as a whole that they can reference as necessary.
A clear list of expectations that maintainers have of them, i.e., a checklist of steps/requirements that they must complete before their PRs can be considered ready for engineering review (including creating product proposals and feature tickets retroactively if their PRs include user-facing changes).

For maintained repositories, they should also get information about who to ping when they're done completing prerequisites for engineering review (e.g. @2u-aurora).

Note: As determined by the maintenance working group, the OSPR bot should not ping maintainers of a repository directly in the welcome message. Instead, it should enclose mentions of maintainers in backticks: `@2u-aurora`.

Information about the maintainers of a repository can be extracted from its catalog-info.yml (example).

Completion criteria

[x] Draft new welcome message.
[x] Have the bot post the new welcome message instead of the existing one.
[x] Implement support for retrieving maintainer info and adding it to the welcome message (if available).

Behavioral specifications

N/A (doesn't change current behavior of OSPR bot, just its messaging)

Documentation updates & improvements criteria

Left to the assignee’s appreciation

Relevant repositories

https://github.com/openedx/openedx-webhooks, and in particular:
- https://github.com/openedx/openedx-webhooks/tree/master/openedx_webhooks/templates
- https://github.com/openedx/openedx-webhooks/blob/master/openedx*webhooks/templates/github_community_pr*comment.md.j2

Review timeline

Flexible.

Notes

According to Feanil:

openedx-webhooks code is gnarly, feel free to ping #openedx-webhooks for help

itsjeyd commented 5 months ago

@feanil @mphilbrick211 @sarina @jmakowski1123 FYI, this is a copy of the OpenCraft ticket that I scheduled for next sprint (starting Tue Apr 16).

itsjeyd commented 5 months ago

Draft of new welcome message is available here.

Check the raw version of the text to see which parts the bot would include conditionally / unconditionally.

sarina commented 5 months ago

Hi @itsjeyd - I'm concerned about this line:

This repository is currently maintained by @{{ maintainers }}. Tag them in a comment and let them know that your changes are ready for review.

I don't think we'll know who the maintainers are in a standard pattern. Could you reword this to explain how to find the maintainers (either by using Backstage or viewing catalog-info.yaml within the repo? (I think it would be better to direct to Backstage, personally)

feanil commented 5 months ago

@sarina FYI, the code is looking at the catalog-info.yaml files on the repo to determine the maintainer so it should be up-to-date. It might get cached for a bit so could be out of date temporarily but not on any large time scale.

sarina commented 5 months ago

Oh sick I had no idea! I guess I don't know anything about the bot these days. Are you going to be able to add in the new message?

itsjeyd commented 4 months ago

@sarina Sorry for the delay in getting back, I was out sick for two weeks and working through my e-mail backlog has been taking some time.

Are you going to be able to add in the new message?

The PR for that is here: https://github.com/openedx/openedx-webhooks/pull/288

sarina commented 4 months ago

@itsjeyd great. Seems like you have a good set of reviewers over there, so I'll let that team finish it up.

itsjeyd commented 4 months ago

Sounds good, thanks @sarina.

itsjeyd commented 2 months ago

https://github.com/openedx/openedx-webhooks/pull/288 has been merged so we're done here 🎉

openedx / openedx-webhooks