From e2683b7f09a3031eb6d5a17bc6a9a479137413f9 Mon Sep 17 00:00:00 2001 From: Alya Abbott Date: Tue, 1 Mar 2022 10:10:06 -0800 Subject: [PATCH] docs: Update contributing guide to clearly point to code review doc. --- CONTRIBUTING.md | 59 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a445efd0ed..6785e08b2d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -172,26 +172,46 @@ Please follow the same guidelines as described above: find an issue labeled ### Working on an issue -- You're encouraged to ask questions on how to best implement or debug your - changes -- the Zulip maintainers are excited to answer questions to help - you stay unblocked and working efficiently. You can ask questions in the - [Zulip development community](https://zulip.com/development-community/), - or on the GitHub issue or pull request. -- We encourage early pull requests for work in progress. Prefix the title of - work in progress pull requests with `[WIP]`, and remove the prefix when - you think it might be mergeable and want it to be reviewed. -- After updating a PR, add a comment to the GitHub thread mentioning that it - is ready for another review. GitHub only notifies maintainers of the - changes when you post a comment, so if you don't, your PR will likely be - neglected by accident! +You're encouraged to ask questions on how to best implement or debug your +changes -- the Zulip maintainers are excited to answer questions to help you +stay unblocked and working efficiently. You can ask questions in the [Zulip +development community](https://zulip.com/development-community/), or on the +GitHub issue or pull request. -It's OK if your first issue takes you a while; that's normal! You'll be -able to work a lot faster as you build experience. +To get early feedback on any UI changes, we encourage you to post screenshots of +your work in the [#design +stream](https://chat.zulip.org/#narrow/stream/101-design) in the [Zulip +development community](https://zulip.com/development-community/) For more advice, see [What makes a great Zulip contributor?](https://zulip.readthedocs.io/en/latest/overview/contributing.html#what-makes-a-great-zulip-contributor) below. +### Submitting a pull request + +If it helps your workflow, you can make a pull request before your work is +ready for review, and we encourage you to do so. Simply prefix the title of +work in progress pull requests with `[WIP]`, and then remove the prefix when +you think it's time for someone else to review your work. + +When you believe your code is ready, follow the [guide on how to review +code](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#how-to-review-code) +to review your own work. You can often find things you missed by taking a step +back to look over your work before asking others to do so. Catching mistakes +yourself will help your PRs be merged faster, and folks will appreciate the +quality and professionalism of your work. + +Once you are satisfied with the quality of your PR, follow the [guidelines on +asking for a code +review](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#asking-for-a-code-review) +to request a review. If you are not sure what's best, simply post a comment on +the main GitHub thread for your PR clearly indicating that it is ready for +review, and the project maintainers will take a look and follow up with next +steps. + +It's OK if your first issue takes you a while; that's normal! You'll be +able to work a lot faster as you build experience. + ### Beyond the first issue To find a second issue to work on, we recommend looking through issues with the same @@ -263,11 +283,9 @@ experience, these are the best predictors of success: [this essay][good-questions-blog] for some good advice. - Learning and practicing [Git commit discipline](https://zulip.readthedocs.io/en/latest/contributing/version-control.html#commit-discipline). -- Submitting carefully tested code. This generally means checking your work - through a combination of automated tests and manually clicking around the - UI trying to find bugs in your work. See - [things to look for](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#things-to-look-for) - for additional ideas. +- Submitting carefully tested code. See our [detailed guide on how to review + code](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#how-to-review-code) + (yours or someone else's). - Posting [screenshots or GIFs](https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html) for frontend changes. @@ -278,7 +296,8 @@ experience, these are the best predictors of success: - Being responsive to feedback on pull requests. This means incorporating or responding to all suggested changes, and leaving a note if you won't be able to address things within a few days. -- Being helpful and friendly on chat.zulip.org. +- Being helpful and friendly on the [Zulip community + server](https://zulip.com/development-community/). [good-questions-blog]: https://jvns.ca/blog/good-questions/