Skip to content

Commit 6dba8b1

Browse files
Mark-SimulacrumMark-Simulacrum
authored
Add documentation about zulip (#289)
1 parent 331c6cf commit 6dba8b1

File tree

5 files changed

+240
-0
lines changed

5 files changed

+240
-0
lines changed

‎src/SUMMARY.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# Rust Forge
22

33
[Overview](./README.md)
4+
- [Chat Platforms](./chat/README.md)
5+
- [Zulip](./chat/zulip.md)
6+
- [Moderation](./chat/zulip/moderation.md)
7+
- [Discord](./chat/discord.md)
48
- [Core](./core/README.md)
59
- [Rust Blog Guidelines](./core/blogs.md)
610
- [Community](./community/README.md)

‎src/chat/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## Chat Platforms
2+
3+
Rust uses a number of different platforms for internal communications between
4+
teams. This does not currently seek to be an exhaustive list, rather documenting
5+
the policies for a select few chat platforms used by the teams.

‎src/chat/discord.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
## Discord
2+
3+
We haven't yet written the documentation for Discord, but if you'd like to help
4+
out, this is the place for it to go!

‎src/chat/zulip.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Zulip
2+
3+
[Rust's Zulip](rust-lang.zulipchat.com) is used by a number of teams, notably
4+
the compiler, language, and library teams, along with their working groups.
5+
6+
Zulip can be an unintuitive platform to get started with. To get started, take a
7+
look at the [getting started
8+
guide](https://zulipchat.com/help/getting-started-with-zulip). For more detail,
9+
examine the [Zulip user documentation](https://zulipchat.com/help/)!
10+
11+
## Where to go for help with using Zulip
12+
13+
If you're testing a feature, or want to get help, the `#zulip` stream is the
14+
place to go. Like elsewhere, the best thing to do is to create a new topic
15+
for each question.
16+
17+
## Getting started
18+
19+
It is recommended to first look at the official [getting started
20+
guide](https://zulipchat.com/help/getting-started-with-zulip). Like Rust itself,
21+
Zulip is a bit special and reading the documentation before digging can be
22+
really helpful.
23+
24+
You'll definitely want to configure the streams that you're subscribed to when
25+
getting started; the default set is quite limited, and there are many groups
26+
that exist beyond it. Subscribing to a stream is very low cost -- it is similar
27+
to being "in" an IRC channel, except that logs are available for all streams,
28+
regardless of subscription status.
29+
30+
It's not necessary to introduce yourself, but feel free to say hello in the
31+
`#new members` stream.
32+
33+
## User groups
34+
35+
User groups can be pinged by anyone with the `@<group>` notation, same as
36+
pinging another user. Groups can be created by anyone, and anyone can join a
37+
group.
38+
39+
Users should feel free to join (or leave) groups on their own. Furthermore,
40+
users should feel free to create groups as needed, though it is currently
41+
expected that this is somewhat rare. You should name your group similar to how
42+
you would name a stream for the same purpose, though groups can be more
43+
fine-grained (or less). For example, `@T-compiler/meeting` currently does not
44+
have a dedicated stream.
45+
46+
## Appropriate conversation
47+
48+
In most streams, you should try to keep conversations related to team business.
49+
The `#general` stream is a bit broader, but even there, discussions should be
50+
closely related to Rust (though may not relate to projects of any particular
51+
team). All channels are expected to be used for discussions related to the Rust
52+
project, though; discussions of (for example) wildlife or sightseeing are not
53+
appropriate.
54+
55+
## Streams
56+
57+
These are similar to "channels" on other platforms (i.e., there should not be
58+
too many). On the other hand, you can choose which streams you subscribe to, so
59+
there can be more than channels on other platforms. Read [Zulip's
60+
documentation](https://zulipchat.com/help/about-streams-and-topics) for more
61+
details.
62+
63+
Streams are appropriate for any Rust official group. For example, working
64+
groups, project groups, teams are all examples of official groups. These should
65+
ideally also be represented in the [team repository](../infra/team-maintenance.md).
66+
67+
### Default streams
68+
69+
**This section is still under debate, and it is not yet clear which direction we
70+
will go. It is non-normative, and should not be used yet for modifications to
71+
the Zulip instance.**
72+
73+
The default set of streams is chosen to allow incoming people to be able to have
74+
at least one place to go that can then, if necessary, direct them to a more
75+
specific location.
76+
77+
Currently that means that every top-level group present on Zulip is by default
78+
visible. Specifically, no stream that contains a `/` will be enabled by default.
79+
80+
Currently this set is:
81+
* general
82+
* t-lang
83+
* t-compiler
84+
* t-libs
85+
* project-ffi-unwind
86+
* project-inline-asm
87+
* project-safe-transmute
88+
* rust-survey-2019
89+
* wg-async-foundations
90+
* wg-database
91+
* wg-formal-methods
92+
* wg-secure-code
93+
* wg-traits
94+
* zulip
95+
96+
An alternative, minimialistic, approach is to use:
97+
* general
98+
* zulip
99+
* announce
100+
* new members
101+
102+
as the default set which forces people into customizing their default set when
103+
starting out.
104+
105+
### Stream naming
106+
107+
A stream should be named such as `#t-{team}/{group name}`. For example,
108+
`#t-compiler/wg-parallel-rustc`. More levels of nesting are fine, e.g., a
109+
working group might want "subgroups" as well, though you may want to omit the
110+
team name in such a case -- keeping the stream name short is good for usability,
111+
to avoid confusion between different streams which share the same prefix.
112+
113+
If no top-level team exists, or the group spans multiple teams (e.g.,
114+
project-ffi-unwind), then the top level team should be omitted.
115+
116+
Streams should be clearly communicated as being for a specific purpose. That
117+
purpose can be broad, but it should likely include a group of some kind (even if
118+
that group is transient, e.g., people who are having trouble with the rust build
119+
system, or people working on the compiler). Furthermore, we do not currently
120+
intend for this Zulip to be a general place for community projects not
121+
affiliated with the Rust organization; if they wish to use Zulip, it is [free
122+
for open source](https://zulipchat.com/for/open-source/).
123+
124+
When a new stream is created, you should announce it in `#announce`. This is
125+
generally done automatically by Zulip.
126+
127+
## Topics
128+
129+
One of these is attached to every message within a given stream (these are the
130+
subdivisions within streams). Topics are generally transient, and live for as
131+
long as there is active discussion on a topic. Thinking of topics like email
132+
subjects is helpful.
133+
134+
New conversation in a given stream should almost always start in a new topic,
135+
not a preexisting one. Unlike (for example) GitHub issues, you should not
136+
attempt to search for a past topic on the same subject. Do not spend too long on
137+
the name of the topic, either, beyond trying to make it short. Topics should
138+
generally be no longer than 20 characters (loosely two to three words), to make
139+
sure it is visible to users.
140+
141+
You should eagerly fork new discussion topics into fresh topics. Note that this
142+
can be done with the tail of another topic (if accidentally you diverge into
143+
another area of discussion).
144+
145+
To fork from an existing topic, see Zulip's documentation
146+
[here](https://zulipchat.com/help/rename-a-topic).
147+
148+
## Messages
149+
150+
Zulip is a unique platform which combines synchronous and
151+
asynchronous communication in one location. You should not generally expect that
152+
your messages will receive a response quickly, and unlike (for example) Discord,
153+
there is likely not much reason to "re-ping" on a particular issue every few
154+
hours as your message is unlikely to vanish into history, being isolated to a
155+
specific topic.
156+
157+
### Linkifiers
158+
159+
Our Zulip supports a lot of helpful linkifiers, and we're generally happy to add
160+
more on request. See [the
161+
documentation](https://rust-lang.zulipchat.com/help/add-a-custom-linkification-filter)
162+
for the format. Propose one in `#zulip`!
163+
164+
Generally, `github-org/repo#123` works for linking to an issue or PR; the below
165+
list gives a few more "special cased" repositories.
166+
167+
Don't forget that standard Markdown syntax for links also works.
168+
169+
We currently support linking to issues on a few repositories:
170+
171+
* rust-lang/rust with [`#4545`](https://github.com/rust-lang/rust/issues/4545) or `rust#4545`
172+
* rust-lang/rfcs with `RFC#3434` or `rfc#3434`
173+
* rust-lang/async-book with `async-book#2334`
174+
* rust-lang-nursery/chalk with `chalk#2334`
175+
* rust-lang/compiler-team with `compiler-team#3433`
176+
* rust-lang-nursery/ena with `ena#3434`
177+
* rust-lang/miri with `miri#3434`
178+
* rust-lang-nursery/polonius with `polonius#3434`
179+
* rust-analyzer/rust-analyzer with `rust-analyzer#3434`
180+
* rust-lang/rustc-guide with `rustc-guide#3434`
181+
* rust-lang/stdarch with `stdarch#3434`
182+
* rust-lang/team with `team#3434`
183+
* rust-lang/unsafe-code-guidelines with `ucg#3434`
184+
185+
We currently support linking to commits on these repositories:
186+
187+
* rust-lang/rust with 40-character long SHAs, e.g., [`25434f898b499876203a3b95c1b38bad5ed2cc5d`](https://github.com/rust-lang/rust/commit/25434f898b499876203a3b95c1b38bad5ed2cc5d)
188+
189+
## Read-only view
190+
191+
Zulip by default requires an account for interaction, though this "bug" is being
192+
actively worked on by the Zulip developers. We currently maintain a read-only
193+
view of the Zulip at <https://zulip-archive.rust-lang.org>; this has relatively
194+
up to date information (we update every 5 minutes). If you're linking to Zulip
195+
from a GitHub comment with the intent to leave a permanent link, this is a good
196+
place to link to. There is not currently good tooling for generating the links.

‎src/chat/zulip/moderation.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Zulip Moderation
2+
3+
Zulip, like all official Rust spaces, is governed by the [Code of
4+
Conduct](https://www.rust-lang.org/policies/code-of-conduct). If you have
5+
concerns, please feel free to escalate to the moderation team.
6+
7+
However, though the moderation team is the top-level body here, it is not the
8+
only place where you can seek help with moderation within Zulip.
9+
10+
One method for reaching the Zulip administrators privately is to email
11+
`zulip-admin.239bd484c0347d2d43214d8581f3e125.show-sender@streams.zulipchat.com`.
12+
See [this page](https://rust-lang.zulipchat.com/help/message-a-stream-by-email)
13+
for details on how this works.
14+
15+
You can also ping the `@mods` group on Zulip; note that this will be public.
16+
17+
It is not currently possible for normal users to self-administrate (e.g., muting
18+
another user). However, each individual stream, including private streams, can
19+
be muted:
20+
21+
## For admins/moderators
22+
23+
Some common actions for moderators are listed [on this
24+
page](https://zulipchat.com/help/moderating-open-organizations).
25+
26+
Notably,
27+
* in ["Organization permissions"](https://rust-lang.zulipchat.com/#organization/organization-permissions)
28+
we can restrict users to mandate invitations before joining (this is the "no new users" button)
29+
30+
New admins/moderators should add themselves to the `mods` group on Zulip. (Note
31+
that this is something that any user can do!)

0 commit comments

Comments
 (0)