docs: Split a CONTRIBUTING.md out of README.md.

Also contains a number of updates, additions, and deletions; this is
essentially a rewrite of the github landing page experience.

CONTRIBUTING.md

@@ -0,0 +1,291 @@
+# Contributing to Zulip
+
+Welcome to the Zulip community!
+
+## Community
+
+The
+[Zulip community server](https://zulip.readthedocs.io/en/latest/chat-zulip-org.html)
+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
+[community norms](http://zulip.readthedocs.io/en/latest/chat-zulip-org.html#community-norms)
+before posting. The Zulip community is also governed by a
+[code of conduct](http://zulip.readthedocs.io/en/latest/code-of-conduct.html).
+
+You can subscribe to zulip-devel@googlegroups.com for a lower traffic (~1
+email/month) way to hear about things like mentorship opportunities with Google
+Code-in, in-person sprints at conferences, and other opportunities to
+contribute.
+
+## Ways to contribute
+
+To make a code or documentation contribution, read our
+[step-by-step guide](#your-first-codebase-contribution) to getting
+started with the Zulip codebase. A small sample of the type of work that
+needs doing:
+* Bug squashing and feature development on our Python/Django
+  [backend](https://github.com/zulip/zulip), web
+  [frontend](https://github.com/zulip/zulip), React Native
+  [mobile app](https://github.com/zulip/zulip-mobile), or Electron
+  [desktop app](https://github.com/zulip/zulip-electron).
+* Building out our
+  [Python API and bots](https://github.com/zulip/python-zulip-api) framework.
+* [Writing an integration](http://zulip.readthedocs.io/en/latest/integration-guide.html).
+* Improving our [user](https://chat.zulip.org/help/) or
+  [developer](https://zulip.readthedocs.io/en/latest/) documentation.
+* [Reviewing code](http://zulip.readthedocs.io/en/latest/code-reviewing.html)
+  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:
+
+* [Reporting issues](#reporting-issues), including both feature requests and
+  bug reports.
+* [Giving feedback](#user-feedback) if you are evaluating or using Zulip.
+* [Translating](https://zulip.readthedocs.io/en/latest/translating.html)
+  Zulip.
+* [Outreach](#zulip-outreach): Star us on GitHub, upvote us
+  on product comparison sites, or write for the Zulip blog.
+
+## 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;
+no one gets it right the first time, and there are a lot of people available
+to help.
+* First, make an account on the
+  [Zulip community server](http://zulip.readthedocs.io/en/latest/chat-zulip-org.html),
+  paying special attention to the community norms. If you'd like, introduce
+  yourself in
+  [#new members](https://chat.zulip.org/#narrow/stream/new.20members), using
+  your name as the topic. Bonus: tell us about your first impressions of
+  Zulip, and anything that felt confusing/broken as you started using the
+  product.
+* Read [What makes a great Zulip contributor](#what-makes-a-great-zulip-contributor).
+* [Install the development environment](https://zulip.readthedocs.io/en/latest/dev-overview.html),
+  getting help in
+  [#development help](https://chat.zulip.org/#narrow/stream/development.20help)
+  if you run into any troubles.
+* Read the
+  [Zulip guide to Git](http://zulip.readthedocs.io/en/latest/git-guide.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/git.20help) if you run
+  into any troubles.
+* Sign the
+  [Dropbox Contributor License Agreement](https://opensource.dropbox.com/cla/).
+
+### Picking 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.
+
+* If you're interested in
+  [mobile](https://github.com/zulip/zulip-mobile/issues?q=is%3Aopen+is%3Aissue),
+  [desktop](https://github.com/zulip/zulip-electron/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/mobile),
+  [#electron](https://chat.zulip.org/#narrow/stream/electron), or
+  [#bots](https://chat.zulip.org/#narrow/stream/bots).
+* For the main server and web repository, start by looking through issues
+  with the label
+  [good first issue](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A"good+first+issue").
+  These are smaller projects particularly suitable for a first contribution.
+* We also partition all of our issues in the main repo 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/new.20members) 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), mobile (React Native), desktop (Electron),
+  documentation (English) or visual design (JavaScript + CSS) issue, and a
+  bit about your programming experience.
+
+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/new.20members) with the
+feature idea and the problem that you're hoping to solve.
+
+Other notes:
+* 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 tests).
+* The full list of issues looking for a contributor can be found with the
+  [help wanted](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
+  label.
+* 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
+
+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'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.
+* 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!
+
+### And beyond
+
+A great place to look for a second issue is to look for 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.
+
+## What makes a great Zulip contributor?
+
+Zulip runs a lot of internship programs, so we have a lot of experience 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.
+* Learning and practicing
+  [Git commit discipline](http://zulip.readthedocs.io/en/latest/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](http://zulip.readthedocs.io/en/latest/code-reviewing.html#things-to-look-for)
+  for additional ideas.
+* Posting
+  [screenshots or GIFs](http://zulip.readthedocs.io/en/latest/screenshot-and-gif-software.html)
+  for frontend changes.
+* 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.
+
+These are also the main criteria we use to select interns for all of our
+internship programs.
+
+## Reporting issues
+
+If you find an easily reproducible bug and/or are experienced in reporting
+bugs, feel free to just open an issue on the relevant project on GitHub.
+
+If you have a feature request or are not yet sure what the underlying bug
+is, the best place to post issues is
+[#issues](https://chat.zulip.org/#narrow/stream/issues) (or
+[#mobile](https://chat.zulip.org/#narrow/stream/mobile) or
+[#electron](https://chat.zulip.org/#narrow/stream/electron)) on the
+[Zulip community server](http://zulip.readthedocs.io/en/latest/chat-zulip-org.html).
+This allows us to interactively figure out what is going on, let you know if
+a similar issue has already been opened, and collect any other information
+we need. Choose a 2-4 word topic that describes the issue, explain the issue
+and how to reproduce it if known, your browser/OS if relevant, and a
+[screenshot or screenGIF](http://zulip.readthedocs.io/en/latest/screenshot-and-gif-software.html)
+if appropriate.
+
+**Reporting security issues**. Please do not report security issues
+  publicly, including on public streams on chat.zulip.org. You can email
+  zulip-security@googlegroups.com. We create a CVE for every security issue.
+
+## User feedback
+
+Nearly every feature we develop starts with a user request. If you are part
+of a group that is either using or considering using Zulip, we would love to
+hear about your experience with the product. If you're not sure what to
+write, here are some questions we're always very curious to know the answer
+to:
+
+* Evaluation: What is the process by which your organization chose or will
+  choose a group chat product?
+* Pros and cons: What are the pros and cons of Zulip for your organization,
+  and the pros and cons of other products you are evaluating?
+* Features: What are the features that are most important for your
+  organization? In the best case scenario, what would your chat solution do
+  for you?
+* Onboarding: If you remember it, what was your impression during your first
+  few minutes of using Zulip? What did you notice, and how did you feel? Was
+  there anything that stood out to you as confusing, or broken, or great?
+* Organization: What does your organization do? How big is the organization?
+  A link to your organization's website?
+
+## Internship programs
+
+Zulip runs internship programs with [Outreachy](https://www.outreachy.org/),
+[Google Summer of Code](https://developers.google.com/open-source/gsoc/),
+and the
+[MIT Externship program](https://alum.mit.edu/students/NetworkwithAlumni/ExternshipProgram),
+and also takes summer interns from Harvard, MIT, and Stanford.
+
+The application process and selection criteria for all our internship
+programs is the same. A few notes:
+* We try to make the application process as valuable for the applicant as
+  possible. Expect high quality code reviews, a supportive community, and
+  publicly viewable patches you can link to from your resume, regardless of
+  whether you are selected.
+* To apply, you'll have to submit at least one pull request to a Zulip
+  repository. Strong applicants for most of our programs typically have
+  several complete pull requests by the time of the application deadline.
+* The main criteria we use is quality of your strongest contributions, and
+  the bullets listed at
+  [What makes a great Zulip contributor](#what-makes-a-great-zulip-contributor).
+
+Zulip also participates in
+[Google Code-In](https://developers.google.com/open-source/gci/). Our
+selection criteria for Finalists and Grand Prize Winners is the same as our
+selection criteria for interns above.
+
+Most of our interns end up sticking around the project long-term, and many
+quickly become core team members. We hope you apply!
+
+## Zulip Outreach
+
+**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.
+* 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-electron), 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 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.
+
+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 longer 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!

README.md

@@ -1,21 +1,12 @@
-**[Zulip overview](#zulip-overview)** |
-**[Community](#community)** |
-**[Installing for dev](#installing-the-zulip-development-environment)** |
-**[Installing for production](#running-zulip-in-production)** |
-**[Ways to contribute](#ways-to-contribute)** |
-**[How to get involved](#how-to-get-involved-with-contributing-to-zulip)** |
-**[License](#license)**
-
 # Zulip overview
 
 Zulip is a powerful, open source group chat application that combines the
 immediacy of real-time chat with the productivity benefits of threaded
 conversations. Zulip is used by open source projects, Fortune 500 companies,
-large standards bodies, and others who need a real-time chat product that
+large standards bodies, and others who need a real-time chat system that
-scales to individuals getting hundreds or thousands of messages a day.
+allows users to easily process hundreds or thousands of messages a day. With
-With over 300 contributors merging over 500 commits a month,
+over 300 contributors merging over 500 commits a month, Zulip is also the
-Zulip is also the largest and fastest growing open source group chat
+largest and fastest growing open source group chat project.
-project.
 
 [![Build Status](https://travis-ci.org/zulip/zulip.svg?branch=master)](https://travis-ci.org/zulip/zulip)
 [![Coverage Status](https://img.shields.io/codecov/c/github/zulip/zulip.svg)](https://codecov.io/gh/zulip/zulip)
@@ -24,255 +15,64 @@ project.
 [![Zulip chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://chat.zulip.org)
 [![Twitter](https://img.shields.io/badge/twitter-@zulip-blue.svg?style=flat)](http://twitter.com/zulip)
 
-## Community
+## Next steps
 
-There are several places online where folks discuss Zulip.
+Click on the appropriate link below. If nothing seems to apply,
+join us on the
+[Zulip community server](https://zulip.readthedocs.io/en/latest/chat-zulip-org.html)
+and tell us what's up!
 
-* The primary place is the
+I am interested in:
-  [Zulip development community Zulip server][czo-doc] at
-  chat.zulip.org.
 
-* For Google Summer of Code students and applicants, we have
+* **Contributing code**. Check out our
-[a mailing list](https://groups.google.com/forum/#!forum/zulip-gsoc)
+  [guide for new contributors](https://zulip.readthedocs.io/en/latest/contributing.html)
-for help, questions, and announcements.  But it's often simpler to
+  to get started. Zulip prides itself on maintaining a clean and well-tested
-[visit chat.zulip.org][czo-doc] instead.
+  codebase, and a stock of hundreds of
+  [beginner-friendly issues](https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).
 
-* We have a [public development discussion mailing list][zulip-devel],
+* **Contributing non-code**.
-zulip-devel, which is currently pretty low traffic because most
+  [Report an issue](https://zulip.readthedocs.io/en/latest/contributing.html#reporting-issue),
-discussions happen in our public Zulip instance.  We use it to
+  [translate](https://zulip.readthedocs.io/en/latest/translating.html) Zulip
-announce Zulip developer community gatherings and ask for feedback on
+  into your language,
-major technical or design decisions.  It has several hundred
+  [write](https://zulip.readthedocs.io/en/latest/contributing.html#zulip-outreach)
-subscribers, so you can use it to ask questions about features or
+  for the Zulip blog, or
-possible bugs, but please don't use it ask for generic help getting
+  [give us feedback](https://zulip.readthedocs.io/en/latest/contributing.html#user-feedback). We
-started as a contributor (e.g. because you want to do Google Summer of
+  would love to hear from you, even if you're just trying the product out.
-Code).  The rest of this page covers how to get involved in the Zulip
-project in detail.
 
-* Zulip also has a [blog](https://blog.zulip.org/) and
+* **Supporting Zulip**. Advocate for your organization to use Zulip, write a
-  [twitter account](https://twitter.com/zulip).
+  review in the mobile app stores, or
+  [upvote Zulip](https://zulip.readthedocs.io/en/latest/contributing.html#zulip-outreach) on
+  product comparison sites.
 
-* Last but not least, we use [GitHub](https://github.com/zulip/zulip)
+* **Checking Zulip out**. The best way to see Zulip in action is to drop by
-to track Zulip-related issues (and store our code, of course).
+  the
-Anybody with a GitHub account should be able to create Issues there
+  [Zulip community server](https://zulip.readthedocs.io/en/latest/chat-zulip-org.html). We
-pertaining to bugs or enhancement requests.  We also use Pull Requests
+  also recommend reading Zulip for
-as our primary mechanism to receive code contributions.
+  [open source](https://zulipchat.com/for/open-source/), Zulip for
+  [companies](https://zulipchat.com/for/companies/), or Zulip for
+  [working groups and part time communities](https://zulipchat.com/for/working-groups-and-communities/).
 
-The Zulip community has a [Code of Conduct][code-of-conduct].
+* **Running a Zulip server**. Setting up a server takes just a couple of
-
+  minutes. Zulip runs on Ubuntu 16.04 Xenial and Ubuntu 14.04 Trusty. The
-[zulip-devel]: https://groups.google.com/forum/#!forum/zulip-devel
+  installation process is
-
-## Installing the Zulip Development environment
-
-The Zulip development environment is the recommended option for folks
-interested in trying out Zulip, since it is very easy to install.
-This is documented in [the developer installation guide][dev-install].
-
-## Running Zulip in production
-
-Zulip in production supports Ubuntu 16.04 Xenial and Ubuntu 14.04
-Trusty. We're happy to support work to enable Zulip to run on
-additional platforms. The installation process is
   [documented here](https://zulip.readthedocs.io/en/latest/prod.html).
+  Commercial support is available; see <https://zulipchat.com/plans> for
+  details.
 
-## Ways to contribute
+* **Using Zulip without setting up a server**. <https://zulipchat.com> offers
+  free and commercial hosting.
 
-Zulip welcomes all forms of contributions!  This page documents the
+* **Applying for a Zulip internship**. Zulip runs internship programs with
-Zulip development process.
+  [Outreachy](https://www.outreachy.org/),
+  [Google Summer of Code](https://developers.google.com/open-source/gsoc/),
+  and the
+  [MIT Externship program](https://alum.mit.edu/students/NetworkwithAlumni/ExternshipProgram),
+  and also takes summer interns from Harvard, MIT, and Stanford.  More
+  information is available
+  [here](https://zulip.readthedocs.io/en/latest/contributing.html#internship-programs).
 
-* **Pull requests**. Before a pull request can be merged, you need to
+You may also be interested in reading our [blog](http://blog.zulip.org/) or
-sign the [Dropbox Contributor License Agreement][cla].  Also,
+following us on [twitter](https://twitter.com/zulip).
-please skim our [commit message style guidelines][doc-commit-style].
-We encourage early pull requests for work in progress. Prefix the title
-of your pull request with `[WIP]` and reference it when asking for
-community feedback. When you are ready for final review, remove
-the `[WIP]`.
-
-* **Testing**. The Zulip automated tests all run automatically when
-you submit a pull request, but you can also run them all in your
-development environment following the instructions in the [testing
-docs][doc-test]. You can also try out [our new desktop
-client][electron], which is now out of beta; we'd appreciate testing and
-[feedback](https://github.com/zulip/zulip-electron/issues/new).
-
-* **Developer Documentation**.  Zulip has a growing collection of
-developer documentation on [Read The Docs][doc].  Recommended reading
-for new contributors includes the [directory structure][doc-dirstruct]
-and [new feature tutorial][doc-newfeat]. You can also improve
-[Zulip.org][z-org].
-
-* **Mailing lists and bug tracker**. Zulip has a [development
-discussion mailing list](#community) and uses [GitHub issues
-][gh-issues].  There are also lists for the [Android][email-android]
-and [iOS][email-ios] apps.  Feel free to send any questions or
-suggestions of areas where you'd love to see more documentation to the
-relevant list! Check out our [bug report guidelines][bug-report]
-before submitting. Please report any security issues you discover to
-zulip-security@googlegroups.com.
-
-* **App codebases**. This repository is for the Zulip server and web
-app (including most integrations).  The
-[beta React Native mobile app][mobile], [Java Android app][Android]
-(see [our mobile strategy][mobile-strategy]),
-[new Electron desktop app][electron], and
-[legacy Qt-based desktop app][desktop] are all separate repositories.
-
-* **Glue code**. We maintain a [Hubot adapter][hubot-adapter] and several
-integrations ([Phabricator][phab], [Jenkins][], [Puppet][], [Redmine][],
-and [Trello][]), plus [node.js API bindings][node], an [isomorphic
- JavaScript library][zulip-js], and a [full-text search PostgreSQL
- extension][tsearch], as separate repos.
-
-* **Translations**.  Zulip is in the process of being translated into
-10+ languages, and we love contributions to our translations.  See our
-[translating documentation][transifex] if you're interested in
-contributing!
-
-* **Code Reviews**. Zulip is all about community and helping each
-other out.  Check out [#code review][code-review] on
-[chat.zulip.org][czo-doc] to help review PRs and give comments on
-other people's work. Everyone is welcome to participate, even those
-new to Zulip! Even just checking out the code, manually testing it,
-and posting on whether or not it worked is valuable.
-
-[cla]: https://opensource.dropbox.com/cla/
-[code-of-conduct]: https://zulip.readthedocs.io/en/latest/code-of-conduct.html
-[dev-install]: https://zulip.readthedocs.io/en/latest/dev-overview.html
-[doc]: https://zulip.readthedocs.io/
-[doc-commit-style]: http://zulip.readthedocs.io/en/latest/version-control.html#commit-messages
-[doc-dirstruct]: http://zulip.readthedocs.io/en/latest/directory-structure.html
-[doc-newfeat]: http://zulip.readthedocs.io/en/latest/new-feature-tutorial.html
-[doc-test]: http://zulip.readthedocs.io/en/latest/testing.html
-[electron]: https://github.com/zulip/zulip-electron
-[gh-issues]: https://github.com/zulip/zulip/issues
-[desktop]: https://github.com/zulip/zulip-desktop
-[android]: https://github.com/zulip/zulip-android
-[mobile]: https://github.com/zulip/zulip-mobile
-[mobile-strategy]: https://github.com/zulip/zulip-android/blob/master/android-strategy.md
-[email-android]: https://groups.google.com/forum/#!forum/zulip-android
-[email-ios]: https://groups.google.com/forum/#!forum/zulip-ios
-[hubot-adapter]: https://github.com/zulip/hubot-zulip
-[jenkins]: https://github.com/zulip/zulip-jenkins-plugin
-[node]: https://github.com/zulip/zulip-node
-[zulip-js]: https://github.com/zulip/zulip-js
-[phab]: https://github.com/zulip/phabricator-to-zulip
-[puppet]: https://github.com/matthewbarr/puppet-zulip
-[redmine]: https://github.com/zulip/zulip-redmine-plugin
-[trello]: https://github.com/zulip/trello-to-zulip
-[tsearch]: https://github.com/zulip/tsearch_extras
-[transifex]: https://zulip.readthedocs.io/en/latest/translating.html#testing-translations
-[z-org]: https://github.com/zulip/zulip.github.io
-[code-review]: https://chat.zulip.org/#narrow/stream/code.20review
-[bug-report]: http://zulip.readthedocs.io/en/latest/bug-reports.html
-
-## Google Summer of Code
-
-We participated in
-[GSoC](https://developers.google.com/open-source/gsoc/) in 2016 (with
-[great results](https://blog.zulip.org/2016/10/13/static-types-in-python-oh-mypy/))
-and [are participating](https://github.com/zulip/zulip.github.io/blob/master/gsoc-ideas.md)
-in 2017 as well.
-
-## How to get involved with contributing to Zulip
-
-First, subscribe to the Zulip [development discussion mailing
-list](#community).
-
-The Zulip project uses a system of labels in our [issue
-tracker][gh-issues] to make it easy to find a project if you don't
-have your own project idea in mind or want to get some experience with
-working on Zulip before embarking on a larger project you have in
-mind:
-
-* [Integrations](https://github.com/zulip/zulip/labels/area%3A%20integrations).
-  Integrate Zulip with another piece of software and contribute it
-  back to the community!  Writing an integration can be a great first
-  contribution.  There's detailed documentation on how to write
-  integrations in [the Zulip integration writing
-  guide](https://zulip.readthedocs.io/en/latest/integration-guide.html).
-
-* [Good first issue](https://github.com/zulip/zulip/labels/good%20first%20issue):
-  Smaller projects that might be a great first contribution.
-
-* [Documentation](https://github.com/zulip/zulip/labels/area%3A%20documentation):
-  The Zulip project loves contributions of new documentation.
-
-* [Help Wanted](https://github.com/zulip/zulip/labels/help%20wanted):
-  A broader list of projects that nobody is currently working on.
-
-* [Platform support](https://github.com/zulip/zulip/labels/Platform%20support):
-  These are open issues about making it possible to install Zulip on a
-  wider range of platforms.
-
-* [Bugs](https://github.com/zulip/zulip/labels/bug): Open bugs.
-
-* [Feature requests](https://github.com/zulip/zulip/labels/enhancement):
-  Browsing this list can be a great way to find feature ideas to
-  implement that other Zulip users are excited about.
-
-* [2016 roadmap milestone](http://zulip.readthedocs.io/en/latest/roadmap.html):
-  The projects that are
-  [priorities for the Zulip project](https://zulip.readthedocs.io/en/latest/roadmap.html).
-  These are great projects if you're looking to make an impact.
-
-Another way to find issues in Zulip is to take advantage of our
-`area:<foo>` convention in separating out issues.  We partition all of
-our issues 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 tickets related to your
-areas of interest.
-
-If you're excited about helping with an open issue, make sure to claim
-the issue by commenting the following in the comment section:
-"**@zulipbot** claim". **@zulipbot** will assign you to the issue and
-label the issue as **in progress**. For more details, check out
-[**@zulipbot**](https://github.com/zulip/zulipbot).
-
-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. It's great to ask
-questions in comments on GitHub issues and pull requests, or
-[on chat.zulip.org][czo-doc].  We'll direct longer discussions to
-Zulip chat, but please post a summary of what you learned from the
-chat, or link to the conversation, in a comment on the GitHub issue.
-
-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, and are happy to support you in adding new features or
-other user experience improvements to Zulip.
-
-If you have a new feature you'd like to add, we recommend you start by
-opening a GitHub issue about the feature idea explaining the problem
-that you're hoping to solve and that you're excited to work on it.  A
-Zulip maintainer will usually reply within a day with feedback on the
-idea, notes on any important issues or concerns, and and often tips on
-how to implement or test it.  Please feel free to ping the thread if
-you don't hear a response from the maintainers -- we try to be very
-responsive so this usually means we missed your message.
-
-For significant changes to the visual design, user experience, data
-model, or architecture, we highly recommend posting a mockup,
-screenshot, or description of what you have in mind to the
-[#design](https://chat.zulip.org/#narrow/stream/design) stream on
-[chat.zulip.org][czo-doc] to get broad feedback before you spend too
-much time on implementation details.
-
-Finally, before implementing a larger feature, we highly recommend
-looking at the
-[new feature tutorial](http://zulip.readthedocs.io/en/latest/new-feature-tutorial.html)
-and [coding style guidelines](http://zulip.readthedocs.io/en/latest/code-style.html)
-on ReadTheDocs.
-
-Feedback on how to make this development process more efficient, fun,
-and friendly to new contributors is very welcome!  Just send an email
-to the [zulip-devel](#community) list with your thoughts.
-
-When you feel like you have completed your work on an issue, post your
-PR to the
-[#code review](https://chat.zulip.org/#narrow/stream/code.20review)
-stream on [chat.zulip.org][czo-doc].  This is our lightweight process
-that gives other developers the opportunity to give you comments and
-suggestions on your work.
 
 ## License
 
@@ -294,6 +94,3 @@ The software includes some works released by third parties under other
 free and open source licenses. Those works are redistributed under the
 license terms under which the works were received. For more details,
 see the ``docs/THIRDPARTY`` file included with this distribution.
-
-
-[czo-doc]: https://zulip.readthedocs.io/en/latest/chat-zulip-org.html

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/index.rst

@@ -38,6 +38,7 @@ Contents:
    :caption: Overview
 
    readme-symlink
+   contributing
    architecture-overview
    directory-structure
    roadmap

docs/linters.md

@@ -68,7 +68,7 @@ extreme cases, but often it can be a simple matter of writing your code
 in a slightly different style to appease the linter.  If you have
 problems getting something to lint, you can submit an unfinished PR
 and ask the reviewer to help you work through the lint problem, or you
-can find other people in the [Zulip Community](readme-symlink.html#community)
+can find other people in the [Zulip Community](chat-zulip-org.html)
 to help you.
 
 Also, bear in mind that 100% of the lint code is open source, so if you

docs/translating.md

@@ -149,8 +149,7 @@ Some useful tips for your translating journey:
 ## Testing translations
 
 This section assumes you have a
-[Zulip development environment](readme-symlink.html#installing-the-zulip-development-environment)
+[Zulip development environment](dev-overview.html) set up.
-setup.
 
 First of all, download the updated resource files from Transifex using the
 `tx pull -a --mode=developer` command (it will require some

docs/webhook-walkthrough.md

@@ -386,7 +386,7 @@ request:
 
 If you would like feedback on your integration as you go, feel free to post a
 message on the [public Zulip instance](https://chat.zulip.org/#narrow/stream/bots).
-You can also create a [`[WIP]` pull request](readme-symlink.html#ways-to-contribute)
+You can also create a [`[WIP]` pull request](contributing.html#working-on-an-issue)
 while you are still working on your integration. See the
 [Git guide](git-guide.html#create-a-pull-request) for more on Zulip's pull
 request process.