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

@@ -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)
+- [Translate](https://zulip.readthedocs.io/en/latest/translating/translating.html)
-  Zulip.
+  Zulip into your language.
-- [Outreach](#zulip-outreach): Star us on GitHub, upvote us
+- [Stay connected](#stay-connected) with Zulip, and [help others
-  on product comparison sites, or write for [the Zulip blog](https://blog.zulip.org/).
+  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,41 +65,64 @@ to help.
   getting help in
   [#development help](https://chat.zulip.org/#narrow/stream/49-development-help)
   if you run into any troubles.
-- Read the
+- Familiarize yourself with [using the development environment](https://zulip.readthedocs.io/en/latest/development/using.html).
-  [Zulip guide to Git](https://zulip.readthedocs.io/en/latest/git/index.html)
+- Go through the [new application feature
-  and do the Git tutorial (coming soon) if you are unfamiliar with
+  tutorial](https://zulip.readthedocs.io/en/latest/tutorials/new-feature-tutorial.html) to get familiar with
-  Git, getting help in
+  how the Zulip codebase is organized and how to find code in it.
-  [#git help](https://chat.zulip.org/#narrow/stream/44-git-help) if
+- Read the [Zulip guide to
-  you run into any troubles. Be sure to check out the
+  Git](https://zulip.readthedocs.io/en/latest/git/index.html) if you
-  [extremely useful Zulip-specific tools page](https://zulip.readthedocs.io/en/latest/git/zulip-tools.html).
+  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
+Now you're ready to pick your first issue! Zulip has several repositories you
-in the main codebase alone. This section will help you find an issue to work
+can check out, depending on your interests. There are hundreds of open issues in
-on.
+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
+Any issue with the "good first issue"
-  [mobile](https://github.com/zulip/zulip-mobile/issues?q=is%3Aopen+is%3Aissue),
+label is a good candidate when you are getting started. In addition, many of the
-  [desktop](https://github.com/zulip/zulip-desktop/issues?q=is%3Aopen+is%3Aissue),
+issues with the "help wanted" label may be approachable as well.
-  or
+
-  [bots](https://github.com/zulip/python-zulip-api/issues?q=is%3Aopen+is%3Aissue)
+- [Server and web app](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
-  development, check the respective links for open issues, or post in
+- [Mobile apps](https://github.com/zulip/zulip-mobile/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
-  [#mobile](https://chat.zulip.org/#narrow/stream/48-mobile),
+- [Desktop app](https://github.com/zulip/zulip-desktop/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
-  [#desktop](https://chat.zulip.org/#narrow/stream/16-desktop), or
+- [Terminal app](https://github.com/zulip/zulip-terminal/issues?q=is%3Aopen+is%3Aissue+label%3A"help+wanted")
-  [#integration](https://chat.zulip.org/#narrow/stream/127-integrations).
+- [Python API bindings and bots](https://github.com/zulip/python-zulip-api/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
-- For the main server and web repository, we recommend browsing
+
-  recently opened issues to look for issues you are confident you can
+### Picking an issue to work on
-  fix correctly in a way that clearly communicates why your changes
+
-  are the correct fix. Our GitHub workflow bot, zulipbot, limits
+There's a lot to learn while making your first pull request, so start small!
-  users who have 0 commits merged to claiming a single issue labeled
+Many first contributions have fewer than 10 lines of changes (not counting
-  with "good first issue" or "help wanted".
+changes to tests).
-- We also partition all of our issues in the main repo into areas like
+
-  admin, compose, emoji, hotkeys, i18n, onboarding, search, etc. Look
+We recommend the following process for finding an issue to work on:
-  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
+1. Read the description of an issue and make sure you understand it.
-  areas of interest.
+2. If it seems promising, poke around the product
-- If the lists of issues are overwhelming, post in
+   (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),
@@ -114,49 +130,56 @@ on.
 documentation (English) or visual design (JavaScript/TypeScript + CSS) issue, and a
 bit about your programming experience and available time.
 
-We also welcome suggestions of features that you feel would be valuable or
+Additional tips for the [main server and web app
-changes that you feel would make Zulip a better open source project. If you
+repository](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22):
-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.
 
-Other notes:
+- 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.
+- 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.
 
-- For a first pull request, it's better to aim for a smaller contribution
+### Claiming an issue
-  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.
 
-### Working on an issue
+#### In the main server and web app repository
 
-To work on an issue, claim it by adding a comment with `@zulipbot claim` to
+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". Some additional notes:
+progress". You can only claim issues with the
-
-- 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
+
 - 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
+  you stay unblocked and working efficiently. You can ask questions in the
-  chat.zulip.org, or on the GitHub issue or pull request.
+  [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
+- Posting good questions. It's very hard to answer a general question like, "How
-  understanding, saying what you've done or tried so far, and including
+  do I do this issue?" When asking for help, explain
-  tracebacks or other error messages if appropriate.
+  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
+email [security@zulip.com](mailto:security@zulip.com). We create a CVE for every
-issue in our released software.
+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
+a strong application.
-2017 had made significant contributions to the project by February
+
-2017, and about half had not. Our
+Our [GSoC project ideas page][gsoc-guide] has lots more details on how
-[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
-Zulip does GSoC, as well as project ideas (though 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)
+In some years, we have also run a Zulip Summer of Code (ZSoC)
-program for students who we didn't have enough slots to accept for
+program for students who we wanted to accept into GSoC but did not have an
-GSoC but were able to find funding for. Student expectations are the
+official slot for. Student expectations are the
-same as with GSoC, and it has no separate application process; your
+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
+Even if you are not logging into the development community on a regular basis,
-perception of projects like Zulip. We've collected a few sites below
+you can still stay connected with the project.
-where we know Zulip has been discussed. Doing everything in the following
+
-list typically takes about 15 minutes.
+- 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
+- "Like" and retweet [our tweets](https://twitter.com/zulip).
-don't already have one.
 
-- [Like Zulip](https://alternativeto.net/software/zulip-chat-server/) on
+- Upvote and post feedback on Zulip on comparison websites. A couple specific
-  AlternativeTo. We recommend upvoting a couple of other products you like
+  ones to highlight:
-  as well, both to give back to their community, and since single-upvote
+
-  accounts are generally given less weight. You can also
+  - [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. Again, we recommend adding a few other products that you like
+    compelling.
-  as well.
-
-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!

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",
         },