From 35ab9de53c5946add56b5693c00899fe8d598a48 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Sun, 12 Feb 2017 13:50:11 -0800 Subject: [PATCH] docs: Document chat.zulip.org. --- README.md | 27 ++++++-------- docs/chat-zulip-org.md | 85 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 98 insertions(+), 15 deletions(-) create mode 100644 docs/chat-zulip-org.md diff --git a/README.md b/README.md index 238125d7cb..03fa9d5be0 100644 --- a/README.md +++ b/README.md @@ -25,18 +25,14 @@ at https://www.zulip.org. There are several places online where folks discuss Zulip. -One of those places is our [public Zulip instance](https://chat.zulip.org/). -You can go through the simple signup process at that link, and then you -will soon be talking to core Zulip developers and other users. To get -help in real time, you will have the best luck finding core developers -roughly between 16:00 UTC and 23:59 UTC. Most questions get a reply -within minutes to a few hours, depending on time of day. +* The primary place is our [public Zulip instance](chat-zulip-org.html). -For Google Summer of Code students and applicants, we have [a mailing -list](https://groups.google.com/forum/#!forum/zulip-gsoc) for help, -questions, and announcements. +* For Google Summer of Code students and applicants, we have +[a mailing list](https://groups.google.com/forum/#!forum/zulip-gsoc) +for help, questions, and announcements. But it's often simpler to +visit chat.zulip.org instead. -We have +* We have [a public mailing list](https://groups.google.com/forum/#!forum/zulip-devel) that is currently pretty low traffic because most discussions happen in our public Zulip instance. We use it to announce Zulip developer @@ -47,13 +43,14 @@ ask for generic help getting started as a contributor (e.g. because you want to do Google Summer of 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/). +* Zulip also has a [blog](https://blog.zulip.org/) and + [twitter account](https://twitter.com/zuliposs). -Last but not least, we use [GitHub](https://github.com/zulip/zulip) to -track Zulip-related issues (and store our code, of course). +* Last but not least, we use [GitHub](https://github.com/zulip/zulip) +to track Zulip-related issues (and store our code, of course). Anybody with a GitHub account should be able to create Issues there -pertaining to bugs or enhancement requests. We also use Pull -Requests as our primary mechanism to receive code contributions. +pertaining to bugs or enhancement requests. We also use Pull Requests +as our primary mechanism to receive code contributions. The Zulip community has a [Code of Conduct][code-of-conduct]. diff --git a/docs/chat-zulip-org.md b/docs/chat-zulip-org.md new file mode 100644 index 0000000000..2fa3f69377 --- /dev/null +++ b/docs/chat-zulip-org.md @@ -0,0 +1,85 @@ +# The chat.zulip.org community + +[chat.zulip.org](https://chat.zulip.org/) is the primary communication +forum for the Zulip community. + +You can go through the simple signup process at that link, and then +you will soon be talking to core Zulip developers and other users. To +get help in real time, you will have the best luck finding core +developers roughly between 16:00 UTC and 23:59 UTC, but the sun never +sleeps on the Zulip development community. Most questions get a reply +within minutes to a few hours, depending on time of day. + +## Not a production installation + +The chat.zulip.org server is frequently deployed off of `master` from +the Zulip Git repository, so please point out anything you notice that +seems wrong! We catch many bugs that escape code review this way. + +The chat.zulip.org server is a development and testing server, not a +production service, so don't use it for anything mission-critical, +secret/embarrassing, etc. + +## Community conventions + +* Send any test messages to + [#test here](https://chat.zulip.org/#narrow/stream/test.20here) or + as a PM to yourself to avoid disrupting others. +* When asking for help, provide the details needed for others to help + you. E.g. include the full traceback in a code block (not a + screenshot), a link to the code or a WIP PR you're having trouble + debugging, etc. +* Ask questions on streams rather than PMing core contributors. + You'll get answers faster since other people can help, and it makes + it possible for other developers to learn from reading the discussion. +* Use @-mentions sparingly. Unlike IRC or Slack, in Zulip, it's + usually easy to see which message you're replying to, so you don't + need to mention your conversation partner in every reply. + Mentioning other users is great for timely questions or making sure + someone who is not online sees your message. +* Converse informally; there's no need to use titles like "Sir". +* Follow the [community code of conduct](code-of-conduct.html). + +## Streams + +There are a few streams worth highlighting that are relevant for +everyone, even non-developers: + +* [#announce](https://chat.zulip.org/#narrow/stream/announce) is for + announcements and discussions thereof; we try to keep traffic there + to a minimum. +* [#design](https://chat.zulip.org/#narrow/stream/design) is where we + discuss the UI design and collect feedback on potential design + changes. We love feedback, so don't hesitate to speak up! +* [#documentation](https://chat.zulip.org/#narrow/stream/documentation) + is where we discuss improving Zulip's user, sysadmin, and developer + documentation. +* [#installation help](https://chat.zulip.org/#narrow/stream/installation.20help) + is for production environment related discussions. +* [#design](https://chat.zulip.org/#narrow/stream/design) is where we + discuss Zulip's UI design and collect feedback on potential design + changes. We love feedback, so don't hesitate to speak up. +* [#test here](https://chat.zulip.org/#narrow/stream/test.20here) is + for sending test messages without inconveniencing other users :). + We recommend muting this stream when not using it. +* [#translation](https://chat.zulip.org/#narrow/stream/translation) is + for discussing Zulip's translations. + +There are dozens of streams for development discussions in the Zulip +community (e.g. one for each app, etc.); check out the /#subscriptions +page to see the descriptions for all of them. Relevant to almost +everyone are these: + +* [#checkins](https://chat.zulip.org/#narrow/stream/checkins) is for + progress updates on what you're working on and it's status; usually + folks post with their name as the topic. Everyone is welcome to + participate! +* [#development help](https://chat.zulip.org/#narrow/stream/development.20help) + is for asking for help with any Zulip server/webapp development work + (using the app streams for help working on one of the apps). +* [#peer review](https://chat.zulip.org/#narrow/stream/peer.20review) + is for getting feedback on your work. We encourage all developers + to comment on work posted here, even if you're new to the Zulip + project; reviewing other PRs is a great way to develop experience, + and even just manually testing a proposed new feature and posting + feedback is super helpful. diff --git a/docs/index.rst b/docs/index.rst index f0dfed229d..c5c323079f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -94,6 +94,7 @@ Contents: code-style mypy code-reviewing + chat-zulip-org .. _code-testing: