mirror of https://github.com/zulip/zulip.git
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.
This commit is contained in:
Rishi Gupta
Tim Abbott
parent
7e9273bc31
commit
ee2ea3750c
|
|
@ -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!
|
||||||
307
README.md
307
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 overview
|
||||||
|
|
||||||
Zulip is a powerful, open source group chat application that combines the
|
Zulip is a powerful, open source group chat application that combines the
|
||||||
immediacy of real-time chat with the productivity benefits of threaded
|
immediacy of real-time chat with the productivity benefits of threaded
|
||||||
conversations. Zulip is used by open source projects, Fortune 500 companies,
|
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.
|
|
||||||
|
|
||||||
[](https://travis-ci.org/zulip/zulip)
|
[](https://travis-ci.org/zulip/zulip)
|
||||||
[](https://codecov.io/gh/zulip/zulip)
|
[](https://codecov.io/gh/zulip/zulip)
|
||||||
|
|
@ -24,255 +15,64 @@ project.
|
||||||
[](https://chat.zulip.org)
|
[](https://chat.zulip.org)
|
||||||
[](http://twitter.com/zulip)
|
[](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
|
||||||
|
installation process is
|
||||||
|
[documented here](https://zulip.readthedocs.io/en/latest/prod.html).
|
||||||
|
Commercial support is available; see <https://zulipchat.com/plans> for
|
||||||
|
details.
|
||||||
|
|
||||||
[zulip-devel]: https://groups.google.com/forum/#!forum/zulip-devel
|
* **Using Zulip without setting up a server**. <https://zulipchat.com> offers
|
||||||
|
free and commercial hosting.
|
||||||
|
|
||||||
## Installing the Zulip Development environment
|
* **Applying for a Zulip internship**. 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. More
|
||||||
|
information is available
|
||||||
|
[here](https://zulip.readthedocs.io/en/latest/contributing.html#internship-programs).
|
||||||
|
|
||||||
The Zulip development environment is the recommended option for folks
|
You may also be interested in reading our [blog](http://blog.zulip.org/) or
|
||||||
interested in trying out Zulip, since it is very easy to install.
|
following us on [twitter](https://twitter.com/zulip).
|
||||||
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).
|
|
||||||
|
|
||||||
## Ways to contribute
|
|
||||||
|
|
||||||
Zulip welcomes all forms of contributions! This page documents the
|
|
||||||
Zulip development process.
|
|
||||||
|
|
||||||
* **Pull requests**. Before a pull request can be merged, you need to
|
|
||||||
sign the [Dropbox Contributor License Agreement][cla]. Also,
|
|
||||||
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
|
## 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
|
free and open source licenses. Those works are redistributed under the
|
||||||
license terms under which the works were received. For more details,
|
license terms under which the works were received. For more details,
|
||||||
see the ``docs/THIRDPARTY`` file included with this distribution.
|
see the ``docs/THIRDPARTY`` file included with this distribution.
|
||||||
|
|
||||||
|
|
||||||
[czo-doc]: https://zulip.readthedocs.io/en/latest/chat-zulip-org.html
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
../CONTRIBUTING.md
|
||||||
|
|
@ -38,6 +38,7 @@ Contents:
|
||||||
:caption: Overview
|
:caption: Overview
|
||||||
|
|
||||||
readme-symlink
|
readme-symlink
|
||||||
|
contributing
|
||||||
architecture-overview
|
architecture-overview
|
||||||
directory-structure
|
directory-structure
|
||||||
roadmap
|
roadmap
|
||||||
|
|
|
||||||
|
|
@ -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
|
in a slightly different style to appease the linter. If you have
|
||||||
problems getting something to lint, you can submit an unfinished PR
|
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
|
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.
|
to help you.
|
||||||
|
|
||||||
Also, bear in mind that 100% of the lint code is open source, so if you
|
Also, bear in mind that 100% of the lint code is open source, so if you
|
||||||
|
|
|
||||||
|
|
@ -149,8 +149,7 @@ Some useful tips for your translating journey:
|
||||||
## Testing translations
|
## Testing translations
|
||||||
|
|
||||||
This section assumes you have a
|
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
|
First of all, download the updated resource files from Transifex using the
|
||||||
`tx pull -a --mode=developer` command (it will require some
|
`tx pull -a --mode=developer` command (it will require some
|
||||||
|
|
|
||||||
|
|
@ -386,7 +386,7 @@ request:
|
||||||
|
|
||||||
If you would like feedback on your integration as you go, feel free to post a
|
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).
|
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
|
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
|
[Git guide](git-guide.html#create-a-pull-request) for more on Zulip's pull
|
||||||
request process.
|
request process.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue