diff --git a/docs/engineering/conventions/pr-reviewing.md b/docs/engineering/conventions/pr-reviewing.md index 208b76b..3c28fd4 100644 --- a/docs/engineering/conventions/pr-reviewing.md +++ b/docs/engineering/conventions/pr-reviewing.md @@ -14,9 +14,9 @@ A few tips to review effectively: - Don't feel that you need to make a fully in-depth review and that you are stupid because you don't understand it at first glance. Giving the full context of the pull request is the responsibility of the author, together with writing documentation and tests. - If a PR lacks sufficient explanation of what has been changed, asking the author to explain themselves is perfectly acceptable. - Prefer reaching consensus over voting. - - Adopting the "Proposals > Discussions > Feelings", try to reach consensus when in conflict over a code change. This means either trying to convince each other using objective metrics, or trying to find a middleground solution that can satisfy both point of views. + - Adopting the "Proposals > Discussions > Feelings", try to reach consensus when in conflict over a code change. This means either trying to convince each other using objective metrics, or trying to find a middle ground solution that can satisfy both point of views. - Don't [bikeshed](https://bikeshed.com/). - - Creating long-winded discussions on trivial topics is really common. Try to recognise when the change you're requesting relates to an objective impact or is purely esthetical. + - Creating long-winded discussions on trivial topics is really common. Try to recognize when the change you're requesting relates to an objective impact or is purely aesthetical. - For code formatting and practices, prefer introducing linters and formatting rules separately rather than discussing them in a PR. - Reviews are a way to learn. - Don't be afraid to review components of code you don't have full knowledge about. It can help you get better knowledge of how that component works. @@ -38,12 +38,12 @@ other stakeholders.) The agenda of the review meeting is prepared by adding a PR to the ["Review Meeting"](https://github.com/orgs/gnolang/projects/4/views/1) project, in the "Agenda" column. Anyone can add PRs to this agenda. Who is in charge of [leading -the review meeting](./pr-triage.md) should proceed to prioritise the agenda: +the review meeting](./pr-triage.md) should proceed to prioritize the agenda: - PRs which need quick rounds of consensus from the core team can be tackled first; mostly if it is expected that any arising discussions will take less than 5 minutes. -- PRs which need "longer" conversations should be tackled next; but prioritising +- PRs which need "longer" conversations should be tackled next; but prioritizing those that are felt as the most pressing and urgent issues, either because of a pending deadline or because they're blocking other, significant work. diff --git a/docs/engineering/conventions/pr-triage.md b/docs/engineering/conventions/pr-triage.md index c9ec595..11a66d0 100644 --- a/docs/engineering/conventions/pr-triage.md +++ b/docs/engineering/conventions/pr-triage.md @@ -1,6 +1,6 @@ # Pull Request Triage -> A process to organise the incoming reviews of PRs and create a system to +> A process to organize the incoming reviews of PRs and create a system to > effectively manage, week after week, all our ongoing work and ensure a swift > feedback loop. @@ -29,18 +29,18 @@ - **Make a first PR review**, as in-depth as you can but deferring where you lack the expertise. - If the PR lacks context, needs more explanation to understand what it's doing, lacks tests or documentation, **feel free to request it and defer reviewing to after that is done.** - The objective here is to ensure the PR doesn't have any major problems and can be handed off for finer-grained review by a codeowner. - - Defer reviews on Draft PRs, unless the author has specifically requested an initial review (but be broad, in these reviews; no need to be specific if the code is not finalised). + - Defer reviews on Draft PRs, unless the author has specifically requested an initial review (but be broad, in these reviews; no need to be specific if the code is not finalized). - For ready PRs, add any review requests which are not already requested by CODEOWNERS. - Place the PR in the correct column in the Pull Requests board. - - _Prioritise community pull requests,_ because they are not paid they lose interest 10x faster. - - **Prioritise this part of the process over any software development for the duration of the triage week.** + - _Prioritize community pull requests,_ because they are not paid they lose interest 10 times faster. + - **Prioritize this part of the process over any software development for the duration of the triage week.** - Prepare the agenda for the review meeting - See the adjacent [Reviewing PRs](./pr-reviewing.md) document for some indications on how to best prepare and structure the review meeting. - Before the GitHub review meeting, work through the PRs you've discussed and viewed this week. - Add them to the "Agenda" column on GitHub and re-order them to make sure that the most important ones are at the top. - On the agenda, anyone can add items, but it is your responsibility to ensure to prioritize them. (If you're up to speed on most PRs, this can take as little as 15 minutes, before the call) - Make sure to know the context for the PRs in the review column, so that you can briefly introduce the changes via voice before kicking off its discussion. - - Morgan and Nemanja are available as alternative leads if neither of the tragers is comfortable with leading it. However, preparing the agenda and being available to give context on the discussed PRs is still the responsibility of those on rotation. + - Morgan and Nemanja are available as alternative leads if neither of the triagers is comfortable with leading it. However, preparing the agenda and being available to give context on the discussed PRs is still the responsibility of those on rotation. - Push development of existing PRs along - There are often important PRs which are blocked for weeks awaiting reviews or feedback from the existing reviewers. - Use the Core Team board to see the status on other PRs and ongoing work, coordinate with Nemanja on which ones to ask for status updates. @@ -65,7 +65,7 @@ There are some existing tools you can use to oversee incoming PRs. - GitHub PR/Issue search sorting - There are some good sorting filters when looking at the [pull requests tab on GitHub](https://github.com/gnolang/gno/pulls) - The default view is a good option to see newly created PRs. - - You can use "Least recently updated" to see the most "stale" conversations on the repostory. + - You can use "Least recently updated" to see the most "stale" conversations on the repository. - But "recently updated" too can be effective as well, to see what PRs have been updated and can likely move forward. - You can use the `-is:draft` query to filter out draft PRs. - Make sure to communicate regularly with your co-triager. Suggestions: @@ -78,12 +78,12 @@ we'll develop one and this section will be updated. ### TODO: Stats -These are ideas for useful stats which illustrate the problem right now; I know of no tool which would let me pick them up, but I'm trying to figure out to get them because it would also help us see the difference after imlpementing this process. +These are ideas for useful stats which illustrate the problem right now; I know of no tool which would let me pick them up, but I'm trying to figure out to get them because it would also help us see the difference after implementing this process. Proposed tool for stats: https://github.com/change-metrics/monocle - (open PRs - draft - closed PRs over time) -- weekly PRs done per team member (anonymised) +- weekly PRs done per team member (anonymized) - average/median time for first and second review - number of reviews received per PR (internal / external) - time-to-completion internal/external percentiles diff --git a/spell-check-dictionary.txt b/spell-check-dictionary.txt index ca6eac6..80f91a2 100644 --- a/spell-check-dictionary.txt +++ b/spell-check-dictionary.txt @@ -78,6 +78,7 @@ hodge-podge jibber-jabber licensable linter +linters natively npm-like onboarding @@ -136,3 +137,16 @@ kanban kanban-style gnolang Todo +bikeshed +aesthetical +se +codeowner +codeowners +CODEOWNERS +gno-core-tech +timezones +triager +triagers +co-triager +co-triagers +UI