From d09997f32e6d7a72ee6b5640e6f008dae18511f2 Mon Sep 17 00:00:00 2001 From: Alya Abbott Date: Tue, 23 Nov 2021 08:31:34 -0800 Subject: [PATCH] dev docs: Improve new contributor guide. The main focus is on improving the instructions around claiming issues to try to create less issue claiming spam. Additionally, we haven't done a detailed update in a few years, and some of the content is stale/irrelevant. --- CONTRIBUTING.md | 328 ++++++++++++++++++------------- tools/linter_lib/custom_check.py | 1 + 2 files changed, 194 insertions(+), 135 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be46c4b732..9bf6dca412 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,18 +8,11 @@ The [Zulip community server](https://zulip.com/developer-community/) is the primary communication forum for the Zulip community. It is a good place to start whether you have a question, are a new contributor, are a new -user, or anything else. Make sure to read the +user, or anything else. Please review our [community norms](https://zulip.com/developer-community/#community-norms) before posting. The Zulip community is also governed by a [code of conduct](https://zulip.readthedocs.io/en/latest/code-of-conduct.html). -You can subscribe to -[zulip-devel-announce@googlegroups.com](https://groups.google.com/g/zulip-devel-announce) -or our [Twitter](https://twitter.com/zulip) account for a very low -traffic (<1 email/month) way to hear about things like mentorship -opportunities with Google Summer of Code, in-person sprints at -conferences, and other opportunities to contribute. - ## Ways to contribute To make a code or documentation contribution, read our @@ -41,18 +34,18 @@ needs doing: and manually testing pull requests. **Non-code contributions**: Some of the most valuable ways to contribute -don't require touching the codebase at all. We list a few of them below: +don't require touching the codebase at all. For example, you can: -- [Reporting issues](#reporting-issues), including both feature requests and +- [Report issues](#reporting-issues), including both feature requests and bug reports. -- [Giving feedback](#user-feedback) if you are evaluating or using Zulip. +- [Give feedback](#user-feedback) if you are evaluating or using Zulip. - [Sponsor Zulip](https://github.com/sponsors/zulip) through the GitHub sponsors program. -- [Translating](https://zulip.readthedocs.io/en/latest/translating/translating.html) - Zulip. -- [Outreach](#zulip-outreach): Star us on GitHub, upvote us - on product comparison sites, or write for [the Zulip blog](https://blog.zulip.org/). +- [Translate](https://zulip.readthedocs.io/en/latest/translating/translating.html) + Zulip into your language. +- [Stay connected](#stay-connected) with Zulip, and [help others + find us](#help-others-find-zulip). -## Your first (codebase) contribution +## Your first codebase contribution This section has a step by step guide to starting as a Zulip codebase contributor. It's long, but don't worry about doing all the steps perfectly; @@ -72,91 +65,121 @@ to help. getting help in [#development help](https://chat.zulip.org/#narrow/stream/49-development-help) if you run into any troubles. -- Read the - [Zulip guide to Git](https://zulip.readthedocs.io/en/latest/git/index.html) - and do the Git tutorial (coming soon) if you are unfamiliar with - Git, getting help in - [#git help](https://chat.zulip.org/#narrow/stream/44-git-help) if - you run into any troubles. Be sure to check out the - [extremely useful Zulip-specific tools page](https://zulip.readthedocs.io/en/latest/git/zulip-tools.html). +- Familiarize yourself with [using the development environment](https://zulip.readthedocs.io/en/latest/development/using.html). +- Go through the [new application feature + tutorial](https://zulip.readthedocs.io/en/latest/tutorials/new-feature-tutorial.html) to get familiar with + how the Zulip codebase is organized and how to find code in it. +- Read the [Zulip guide to + Git](https://zulip.readthedocs.io/en/latest/git/index.html) if you + are unfamiliar with Git or Zulip's rebase-based Git workflow, + getting help in [#git + help](https://chat.zulip.org/#narrow/stream/44-git-help) if you run + into any troubles. Even Git experts should read the [Zulip-specific + Git tools + page](https://zulip.readthedocs.io/en/latest/git/zulip-tools.html). -### Picking an issue +### Where to look for an issue -Now, you're ready to pick your first issue! There are hundreds of open issues -in the main codebase alone. This section will help you find an issue to work -on. +Now you're ready to pick your first issue! Zulip has several repositories you +can check out, depending on your interests. There are hundreds of open issues in +the [main Zulip server and web app +repository](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +alone. -- If you're interested in - [mobile](https://github.com/zulip/zulip-mobile/issues?q=is%3Aopen+is%3Aissue), - [desktop](https://github.com/zulip/zulip-desktop/issues?q=is%3Aopen+is%3Aissue), - or - [bots](https://github.com/zulip/python-zulip-api/issues?q=is%3Aopen+is%3Aissue) - development, check the respective links for open issues, or post in - [#mobile](https://chat.zulip.org/#narrow/stream/48-mobile), - [#desktop](https://chat.zulip.org/#narrow/stream/16-desktop), or - [#integration](https://chat.zulip.org/#narrow/stream/127-integrations). -- For the main server and web repository, we recommend browsing - recently opened issues to look for issues you are confident you can - fix correctly in a way that clearly communicates why your changes - are the correct fix. Our GitHub workflow bot, zulipbot, limits - users who have 0 commits merged to claiming a single issue labeled - with "good first issue" or "help wanted". -- We also partition all of our issues in the main repo into areas like +Any issue with the "good first issue" +label is a good candidate when you are getting started. In addition, many of the +issues with the "help wanted" label may be approachable as well. + +- [Server and web app](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +- [Mobile apps](https://github.com/zulip/zulip-mobile/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +- [Desktop app](https://github.com/zulip/zulip-desktop/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +- [Terminal app](https://github.com/zulip/zulip-terminal/issues?q=is%3Aopen+is%3Aissue+label%3A"help+wanted") +- [Python API bindings and bots](https://github.com/zulip/python-zulip-api/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) + +### Picking an issue to work on + +There's a lot to learn while making your first pull request, so start small! +Many first contributions have fewer than 10 lines of changes (not counting +changes to tests). + +We recommend the following process for finding an issue to work on: + +1. Read the description of an issue and make sure you understand it. +2. If it seems promising, poke around the product + (on [chat.zulip.org](https://chat.zulip.org) or in the development + environment) until you know how the piece being + described fits into the bigger picture. If after some exploration the + description seems confusing or ambiguous, post a question on the GitHub + issue, as others may benefit from the clarification as well. +3. When you find an issue you like, try to get started working on it. See if you + can find the part of the code you'll need to modify (`git grep` is your + friend!) and get some idea of how you'll approach the problem. +4. If you feel lost, that's OK! Go through these steps again with another issue. + There's plenty to work on, and the exploration you do will help you learn + more about the project. + +Note that you are _not_ claiming an issue while you are iterating through steps +1-4. _Before you claim an issue_, you should be confident that you will be able to +tackle it effectively. + +If the lists of issues are overwhelming, you can post in +[#new members](https://chat.zulip.org/#narrow/stream/95-new-members) with a +bit about your background and interests, and we'll help you out. The most +important thing to say is whether you're looking for a backend (Python), +frontend (JavaScript and TypeScript), mobile (React Native), desktop (Electron), +documentation (English) or visual design (JavaScript/TypeScript + CSS) issue, and a +bit about your programming experience and available time. + +Additional tips for the [main server and web app +repository](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22): + +- We especially recommend browsing recently opened issues, as there are more + likely to be easy ones for you to find. +- All issues are partitioned into areas like admin, compose, emoji, hotkeys, i18n, onboarding, search, etc. Look through our [list of labels](https://github.com/zulip/zulip/labels), and click on some of the `area:` labels to see all the issues related to your areas of interest. -- If the lists of issues are overwhelming, post in - [#new members](https://chat.zulip.org/#narrow/stream/95-new-members) with a - bit about your background and interests, and we'll help you out. The most - important thing to say is whether you're looking for a backend (Python), - frontend (JavaScript and TypeScript), mobile (React Native), desktop (Electron), - documentation (English) or visual design (JavaScript/TypeScript + CSS) issue, and a - bit about your programming experience and available time. +- Avoid issues with the "difficult" label unless you + understand why it is difficult and are highly confident you can resolve the + issue correctly and completely. -We also welcome suggestions of features that you feel would be valuable or -changes that you feel would make Zulip a better open source project. If you -have a new feature you'd like to add, we recommend you start by posting in -[#new members](https://chat.zulip.org/#narrow/stream/95-new-members) with the -feature idea and the problem that you're hoping to solve. +### Claiming an issue -Other notes: +#### In the main server and web app repository -- For a first pull request, it's better to aim for a smaller contribution - than a bigger one. Many first contributions have fewer than 10 lines of - changes (not counting changes to tests). -- The full list of issues explicitly looking for a contributor can be - found with the - [good first issue](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) - and - [help wanted](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) - labels. Avoid issues with the "difficult" label unless you - understand why it is difficult and are confident you can resolve the - issue correctly and completely. Issues without one of these labels - are fair game if Tim has written a clear technical design proposal - in the issue, or it is a bug that you can reproduce and you are - confident you can fix the issue correctly. -- For most new contributors, there's a lot to learn while making your first - pull request. It's OK if it takes you a while; that's normal! You'll be - able to work a lot faster as you build experience. +Post a comment with `@zulipbot claim` to +the issue thread. [Zulipbot](https://github.com/zulip/zulipbot) is a GitHub +workflow bot; it will assign you to the issue and label the issue as "in +progress". You can only claim issues with the +[good first issue](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) +or +[help wanted](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +labels. Zulipbot will give you an error if you try to claim an issue +without one of those labels. + +New contributors can only claim one issue until their first pull request is +merged. This is to encourage folks to finish ongoing work before starting +something new. If you would like to pick up a new issue while waiting for review +on an almost-ready pull request, you can post a comment to this effect on the +issue you're interested in. + +#### In other Zulip repositories + +There is no bot for other repositories, so you can simply post a comment saying +that you'd like to work on the issue. + +Please follow the same guidelines as described above: find an issue labeled +"good first issue" or "help wanted", and only pick up one issue at a time to +start with. ### Working on an issue -To work on an issue, claim it by adding a comment with `@zulipbot claim` to -the issue thread. [Zulipbot](https://github.com/zulip/zulipbot) is a GitHub -workflow bot; it will assign you to the issue and label the issue as "in -progress". Some additional notes: - -- You can only claim issues with the - [good first issue](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) - or - [help wanted](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) - labels. Zulipbot will give you an error if you try to claim an issue - without one of those labels. - 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 on - chat.zulip.org, or on the GitHub issue or pull request. + you stay unblocked and working efficiently. You can ask questions in the + [Zulip development community](https://zulip.com/developer-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. @@ -165,22 +188,55 @@ progress". Some additional notes: changes when you post a comment, so if you don't, your PR will likely be neglected by accident! -### And beyond +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. -A great place to look for a second issue is to look for issues with the same +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. + +### Beyond the first issue + +To find a second issue to work on, we recommend looking through issues with the same `area:` label as the last issue you resolved. You'll be able to reuse the work you did learning how that part of the codebase works. Also, the path to becoming a core developer often involves taking ownership of one of these area labels. +### Common questions + +- **What if somebody is already working on the issue I want do claim?** There + are lots of issue to work on! If somebody else is actively working on the + issue, you can find a different one, or help with + reviewing their work. +- **What if somebody else claims an issue while I'm figuring out whether or not to + work on it?** No worries! You can contribute by providing feedback on + their pull request. If you've made good progress in understanding part of the + codebase, you can also find another "help wanted" issue in the same area to + work on. +- **What if there is already a pull request for the issue I want to work on?** + Start by reviewing the existing work. If you agree with the approach, you can + use the existing pull request (PR) as a starting point for your contribution. If + you think a different approach is needed, you can post a new PR, with a comment that clearly + explains _why_ you decided to start from scratch. +- **Can I come up with my own feature idea and work on it?** We welcome + suggestions of features or other improvements that you feel would be valuable. If you + have a new feature you'd like to add, we recommend you start by posting in + [#new members](https://chat.zulip.org/#narrow/stream/95-new-members) with the + feature idea and the problem that you're hoping to solve. + ## What makes a great Zulip contributor? Zulip has a lot of experience working with new contributors. In our experience, these are the best predictors of success: -- Posting good questions. This generally means explaining your current - understanding, saying what you've done or tried so far, and including - tracebacks or other error messages if appropriate. +- Posting good questions. It's very hard to answer a general question like, "How + do I do this issue?" When asking for help, explain + your current understanding, including what you've done or tried so far and where + you got stuck. Post tracebacks or other error messages if appropriate. For + more information, check out the ["Getting help" section of our community + guidelines](https://zulip.com/developer-community/#getting-help) and + [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 @@ -191,11 +247,17 @@ experience, these are the best predictors of success: - Posting [screenshots or GIFs](https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html) for frontend changes. +- Clearly describing what you have implemented and why. For example, if your + implementation differs from the issue description in some way or is a partial + step towards the requirements described in the issue, be sure to call + out those differences. - 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. +[good-questions-blog]: https://jvns.ca/blog/good-questions/ + These are also the main criteria we use to select candidates for all of our outreach programs. @@ -219,8 +281,8 @@ if appropriate. **Reporting security issues**. Please do not report security issues publicly, including on public streams on chat.zulip.org. You can -email security@zulip.com. We create a CVE for every security -issue in our released software. +email [security@zulip.com](mailto:security@zulip.com). We create a CVE for every +security issue in our released software. ## User feedback @@ -243,6 +305,10 @@ to: - Organization: What does your organization do? How big is the organization? A link to your organization's website? +You can contact us in the [#feedback stream of the Zulip development +community](https://chat.zulip.org/#narrow/stream/137-feedback) or +by emailing [support@zulip.com](mailto:support@zulip.com). + ## Outreach programs Zulip participates in [Google Summer of Code @@ -278,70 +344,62 @@ important parts of the project. We hope you apply! ### Google Summer of Code The largest outreach program Zulip participates in is GSoC (14 -students in 2017; 11 in 2018; 17 in 2019; 18 in 2020). While we don't control how +students in 2017; 11 in 2018; 17 in 2019; 18 in 2020; 18 in 2021). While we +don't control how many slots Google allocates to Zulip, we hope to mentor a similar -number of students in future summers. +number of students in future summers. Check out our [blog +post](https://blog.zulip.com/2021/09/30/google-summer-of-code-2021/) to learn +about the GSoC 2021 experience and our participants' accomplishments. If you're reading this well before the application deadline and want to make your application strong, we recommend getting involved in the community and fixing issues in Zulip now. Having good contributions and building a reputation for doing good work is the best way to have -a strong application. About half of Zulip's GSoC students for Summer -2017 had made significant contributions to the project by February -2017, and about half had not. Our -[GSoC project ideas page][gsoc-guide] has lots more details on how -Zulip does GSoC, as well as project ideas (though the project idea +a strong application. + +Our [GSoC project ideas page][gsoc-guide] has lots more details on how +Zulip does GSoC, as well as project ideas. Note, however, that the project idea list is maintained only during the GSoC application period, so if you're looking at some other time of year, the project list is likely -out-of-date). +out-of-date. -We also have in some past years run a Zulip Summer of Code (ZSoC) -program for students who we didn't have enough slots to accept for -GSoC but were able to find funding for. Student expectations are the -same as with GSoC, and it has no separate application process; your +In some years, we have also run a Zulip Summer of Code (ZSoC) +program for students who we wanted to accept into GSoC but did not have an +official slot for. Student expectations are the +same as with GSoC, and ZSoC has no separate application process; your GSoC application is your ZSoC application. If we'd like to select you for ZSoC, we'll contact you when the GSoC results are announced. [gsoc-guide]: https://zulip.readthedocs.io/en/latest/contributing/gsoc-ideas.html [gsoc-faq]: https://developers.google.com/open-source/gsoc/faq -## Zulip outreach +## Stay connected -**Upvoting Zulip**. Upvotes and reviews make a big difference in the public -perception of projects like Zulip. We've collected a few sites below -where we know Zulip has been discussed. Doing everything in the following -list typically takes about 15 minutes. +Even if you are not logging into the development community on a regular basis, +you can still stay connected with the project. + +- Follow us [on Twitter](https://twitter.com/zulip). +- Subscribe to [our blog](https://blog.zulip.org/). +- Join or follow the project [on LinkedIn](https://www.linkedin.com/company/zulip-project/). + +## Help others find Zulip + +Here are some ways you can help others find Zulip: - Star us on GitHub. There are four main repositories: [server/web](https://github.com/zulip/zulip), [mobile](https://github.com/zulip/zulip-mobile), [desktop](https://github.com/zulip/zulip-desktop), and [Python API](https://github.com/zulip/python-zulip-api). -- [Follow us](https://twitter.com/zulip) on Twitter. -For both of the following, you'll need to make an account on the site if you -don't already have one. +- "Like" and retweet [our tweets](https://twitter.com/zulip). -- [Like Zulip](https://alternativeto.net/software/zulip-chat-server/) on - AlternativeTo. We recommend upvoting a couple of other products you like - as well, both to give back to their community, and since single-upvote - accounts are generally given less weight. You can also - [upvote Zulip](https://alternativeto.net/software/slack/) on their page - for Slack. -- [Add Zulip to your stack](https://stackshare.io/zulip) on StackShare, star - it, and upvote the reasons why people like Zulip that you find most - compelling. Again, we recommend adding a few other products that you like - as well. +- Upvote and post feedback on Zulip on comparison websites. A couple specific + ones to highlight: -We have a doc with more detailed instructions and a few other sites, if you -have been using Zulip for a while and want to contribute more. - -**Blog posts**. Writing a blog post about your experiences with Zulip, or -about a technical aspect of Zulip can be a great way to spread the word -about Zulip. - -We also occasionally [publish](https://blog.zulip.org/) long-form -articles related to Zulip. Our posts typically get tens of thousands -of views, and we always have good ideas for blog posts that we can -outline but don't have time to write. If you are an experienced writer -or copyeditor, send us a portfolio; we'd love to talk! + - [AlternativeTo](https://alternativeto.net/software/zulip-chat-server/). You can also + [upvote Zulip](https://alternativeto.net/software/slack/) on their page + for Slack. + - [Add Zulip to your stack](https://stackshare.io/zulip) on StackShare, star + it, and upvote the reasons why people like Zulip that you find most + compelling. diff --git a/tools/linter_lib/custom_check.py b/tools/linter_lib/custom_check.py index 7483a7002d..22a622728d 100644 --- a/tools/linter_lib/custom_check.py +++ b/tools/linter_lib/custom_check.py @@ -870,6 +870,7 @@ markdown_rules = RuleList( }, { "pattern": r"\][(][^#h]", + "exclude_pattern": "mailto:", "include_only": {"README.md", "CONTRIBUTING.md"}, "description": "Use absolute links from docs served by GitHub", },