Skip to content

Commit a5d42ed

Browse files
batpigandmekgrytePlaneshifter
authored
docs: add Zulip guide
PR-URL: #10921 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Co-authored-by: Philipp Burckhardt <pburckhardt@outlook.com> Reviewed-by: Philipp Burckhardt <pburckhardt@outlook.com>
1 parent 8448f5a commit a5d42ed

1 file changed

Lines changed: 136 additions & 0 deletions

File tree

‎docs/contributing/zulip_guide.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
<!-- lint disable expected-html-sections -->
22+
23+
# Zulip Guide
24+
25+
> Guide to the stdlib Zulip chat.
26+
27+
This guide provides best practices and community norms for the [**stdlib Zulip chat**][stdlib-zulip], home of the stdlib community (see [announcement][zulip-announcement]). Everyone is welcome to join or browse the web-public channels (which you can see without signing up). The community norms and guidelines provided in this document are to help ensure that everyone can get the most out of this platform and, hopefully, have a positive experience.
28+
29+
## Getting Started
30+
31+
When you first join, a welcome bot will greet you and share some tips specific to stdlib on how to participate effectively. If you're new to Zulip, you may also want to check out [Zulip's official getting started guide][zulip-getting-started] for a quick overview of how the platform works. If you've used other chat platforms, such as Slack or Discord, things should feel pretty familiar. The one key difference is that Zulip organizes conversations into "topics" rather than "threads". This allows for more focused discussions and makes it easier to follow specific conversations without getting lost in a stream of messages. For more on this, see [Zulip's introduction to topics][zulip-intro-to-topics].
32+
33+
We encourage you to come say hello and tell us a bit about yourself in the [**#introductions**][stdlib-introductions] channel.
34+
35+
## Community Norms
36+
37+
### Where to post
38+
39+
First and foremost, whenever possible, try to post your questions **in public** (rather than sending direct messages, a.k.a. DMs). Asking questions in public is the fastest way to get a response, as more people can help, _plus_ it's likely that someone else will benefit from finding out the answer to your question. The stdlib team is active in the chat, so you shouldn't need to use **@-mentions** by default.
40+
41+
Each channel has a description (don't worry too much about posting in the "right" channel—moderators can help [move content][zulip-move-content] if needed), and conversations are organized into [**topics**][zulip-intro-to-topics]. If you're starting a new discussion, try to pick a brief, descriptive topic name that captures the subject of your message. Topic names also help others find relevant information from past conversations (learn more about [Zulip search filters here][zulip-search-filters]). You can edit a topic name at any time, so if you realize that your original topic name isn't quite right, feel free to update it.
42+
43+
Because it's easy to move content around, please **do NOT cross-post**. Not only can this be confusing, but you risk duplication of effort if multiple people respond to the same question in different channels.
44+
45+
#### Channels
46+
47+
When you first join, you'll automatically be subscribed to several "default" channels. However, there are more channels you might want to explore.
48+
49+
The channels are roughly organized into categories in the left-hand sidebar. At the bottom, you can click on "Browse Channels" to see the full list.
50+
51+
Some categories and channels of interest include:
52+
53+
- **General Interest**
54+
55+
- **announcements**: Announcements everyone should see, including new releases, blog posts, and public events.
56+
- **general**: General topics.
57+
- **office-hours**: Information related to stdlib's weekly [office hours][stdlib-office-hours].
58+
- **water-cooler**: A place to discuss random topics, unrelated to stdlib and its development.
59+
60+
- **Feedback & Support**
61+
62+
- **case-studies**: Using stdlib in your application? Got a cool new demo? Share it here!
63+
- **feedback**: Post your reactions to or feedback on using stdlib.
64+
- **problems**: For reporting and discussing issues in using stdlib.
65+
- **user-questions**: For questions about how to accomplish your goals with stdlib.
66+
67+
- **GSOC**
68+
69+
- **gsoc-questions**: Interested in participating in Google Summer of Code? Have questions? Ask here!
70+
71+
- **Contributors**
72+
73+
- **dev**: General development topics.
74+
- **dev-questions**: Ask questions related to developing stdlib.
75+
- **getting-started**: Are you a new contributor? Post your questions here!
76+
- **introductions**: Interested in contributing to stdlib? Please introduce yourself here!
77+
- **review-requests**: Requests for PR reviews.
78+
79+
- **Development**: Channels related to specific stdlib namespaces, and other areas such as documentation and tooling.
80+
81+
- **GitHub**: These are feeds generated from GitHub activity, such as new issues and pull requests. You can use these channels to keep up with the latest activity in the project.
82+
83+
- **Other**
84+
85+
- **sandbox**: Experiment with Zulip here.
86+
- **zulip**: Questions and discussion about using Zulip.
87+
88+
### Custom Linkifiers
89+
90+
We've set up some [custom linkifiers][zulip-linkifiers] to make it easy to share links to GitHub issues and pull requests. If you type **`#1234`** in a message, it will automatically link to the issue or PR with that number in the main [stdlib GitHub repository][stdlib-github-repo]. There's also a special linkifier for the [stdlib Google Summer of Code repo][stdlib-gsoc-repo]; you simply type **`#G{id-number}`**. Note that these work for both issues and pull requests (GitHub uses the same numbering for both).
91+
92+
### Code of Conduct
93+
94+
The [stdlib Code of Conduct][stdlib-code-of-conduct] applies to all community spaces, including stdlib's Zulip. Should you encounter an issue, [Zulip's reporting tools][zulip-reporting] and our moderation team will be notified and available to assist.
95+
96+
## Feedback and Suggestions
97+
98+
If you have feedback or suggestions about improving our Zulip community, don't hesitate to share your thoughts. We have a special meta channel, [**#zulip**][stdlib-zulip-channel], for discussing community-related topics. For more general feedback, there's also the aptly-named [**#feedback**][stdlib-feedback-channel] channel.
99+
100+
The best part of open source is the community, so we're committed to making our Zulip a welcoming and inclusive space for everyone. We look forward to chatting with you there!
101+
102+
<section class="links">
103+
104+
[stdlib-zulip]: https://stdlib.zulipchat.com
105+
106+
[zulip-announcement]: https://blog.stdlib.io/announcing-zulip/
107+
108+
[stdlib-code-of-conduct]: https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md
109+
110+
[zulip-reporting]: https://zulip.com/help/report-a-message
111+
112+
[zulip-getting-started]: https://zulip.com/help/getting-started-with-zulip
113+
114+
[zulip-intro-to-topics]: https://zulip.com/help/introduction-to-topics
115+
116+
[stdlib-introductions]: https://stdlib.zulipchat.com/#narrow/channel/546733-introductions
117+
118+
[zulip-move-content]: https://zulip.com/help/move-content-to-another-channel
119+
120+
[zulip-search-filters]: https://zulip.com/help/search-for-messages#search-filters
121+
122+
[zulip-linkifiers]: https://zulip.com/help/add-a-custom-linkifier
123+
124+
[stdlib-github-repo]: https://github.com/stdlib-js/stdlib
125+
126+
[stdlib-gsoc-repo]: https://github.com/stdlib-js/google-summer-of-code
127+
128+
[stdlib-zulip-channel]: https://stdlib.zulipchat.com/#narrow/channel/546662-zulip
129+
130+
[stdlib-feedback-channel]: https://stdlib.zulipchat.com/#narrow/channel/546708-feedback
131+
132+
[stdlib-office-hours]: https://github.com/stdlib-js/meetings/issues?q=sort:updated-desc%20is:issue%20label:%22Office%20Hours%22
133+
134+
</section>
135+
136+
<!-- /.links -->

0 commit comments

Comments
 (0)