Skip to content

Commit 4506105

Browse files
ChristianKuehnelChristianKuehnel
authored
Discourse migration - First draft of roadmap and user guide (#45)
* First draft of roadmap and user guide * addressed review comments * addresses Philips email comments * removed inline html * removed roadmap, using Epic #47 instead
1 parent 36b2351 commit 4506105

File tree

1 file changed

+155
-0
lines changed

1 file changed

+155
-0
lines changed

‎discourse_migration/userguide.md

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# User guide for the migration of the mailing lists
2+
3+
This document is intended to help LLVM users to migrate from the mailing lists to
4+
Discourse. Discourse two basic ways for interaction: Via the [web
5+
UI](https://llvm.discourse.group/) and via emails.
6+
7+
## Setting up your account
8+
9+
The easiest way is to create an account using your GitHub account:
10+
11+
1. Navigate to https://llvm.discourse.group/
12+
1. Click on "Sign Up" in the top right corner.
13+
1. Choose "With GitHub" on the right side and log in with your GitHub account.
14+
15+
## Structure of Discourse
16+
17+
Discourse's structure is similar to a set of mailing lists, however different
18+
terms are used there. To help with the transition, here's a translation table
19+
for the terms:
20+
21+
| Mailing list | Discourse |
22+
|--------------|-----------|
23+
| *Mailing list*, consists of threads | *category*, consists of topics |
24+
| *thread*, consists of emails | *topic*, consists of posts |
25+
| *email* | *post* |
26+
27+
## Setting up email interactions
28+
29+
Some folks want to interact with Discourse purely via their email program. Here
30+
are the typical use cases:
31+
32+
* You can [subscribe to a category or topic](https://discourse.mozilla.org/t/how-do-i-subscribe-to-categories-and-topics/16024)
33+
* You can reply to a post, including quoting other peoples texts
34+
([tested](https://llvm.discourse.group/t/email-interaction-with-discourse/3306/4) on GMail).
35+
* [Quoting previous topics in an reply](https://meta.discourse.org/t/single-quote-block-dropped-in-email-reply/144802)
36+
* **TODO:** Creating new topics via email is
37+
[supported](https://meta.discourse.org/t/start-a-new-topic-via-email/62977)
38+
but not configured at the moment. We would need to set up an email address
39+
per category and give Discourse POP3 access to that email account. This sounds
40+
like a solvable issue.
41+
* You can filter incoming emails in your email client by category using the
42+
`List-ID` email header field.
43+
44+
## Mapping of mailing lists to categories
45+
46+
This table explains the mapping from mailing lists to categories in Discourse.
47+
The email addresses of these categories will remain the same, after the
48+
migration.
49+
50+
| Mailing lists | category in Discourse |
51+
|-----------------------|--------------------|
52+
| All-commits | no migration at the moment |
53+
| Bugs-admin | no migration at the moment |
54+
| cfe-commits | no migration at the moment |
55+
| cfe-dev | llvm-project/clang |
56+
| cfe-users | **TODO** llvm-project/clang or create new category? |
57+
| clangd-dev | llvm-project/clangd |
58+
| devmtg-organizers | **TODO** create new category |
59+
| Docs | infrastructure/documentation |
60+
| eurollvm-organizers | **TODO** create new category |
61+
| flang-commits | no migration at the moment |
62+
| flang-dev | llvm-project/flang |
63+
| gsoc | community/gsoc |
64+
| libc-commits | no migration at the moment |
65+
| libc-dev | llvm-project/libc |
66+
| Libclc-dev | **TODO** create new category |
67+
| libcxx-bugs | no migration at the moment |
68+
| libcxx-commits | no migration at the moment |
69+
| libcxx-dev | llvm-project/libcxx |
70+
| lldb-commits | no migration at the moment |
71+
| lldb-dev | llvm-project/lldb |
72+
| llvm-admin | **TODO** create new category |
73+
| llvm-announce | **TODO** create new category |
74+
| llvm-branch-commits | no migration at the moment |
75+
| llvm-bugs | no migration at the moment |
76+
| llvm-commits | no migration at the moment |
77+
| llvm-dev | llvm-project/llvm |
78+
| llvm-devmeeting | community/devmtg |
79+
| llvm-foundation | **TODO** create new category|
80+
| Mlir-commits | no migration at the moment |
81+
| Openmp-commits | no migration at the moment |
82+
| Openmp-dev | llvm-project/openmp |
83+
| Parallel_libs-commits | no migration at the moment |
84+
| Parallel_libs-dev | **TODO** use llvm-project/pstl or create new category ? |
85+
| Release-testers | **TODO** create new category |
86+
| Test-list | **TODO** create new category |
87+
| vmkit-commits | no migration at the moment |
88+
| WiCT | **TODO** |
89+
| www-scripts | **TODO** |
90+
91+
**TODO:** add discourse links once the list is finalized
92+
93+
## FAQ
94+
95+
### I don't want to use a web UI
96+
97+
You can do most of the communication with your email client (see section on
98+
Setting up email interactions above). You only need to set up your account once
99+
and then configure which categories you want to subscribe to.
100+
101+
### How do I send a private message?
102+
103+
On the mailing list you have the opportunity to reply only to the sender of
104+
the email, not to the entire list. That is not supported when replying via
105+
email on Discourse. However you can send someone a private message via the
106+
Web UI: Click on the user's name above a post and then on `Message`.
107+
108+
Also Discourse does not expose users' email addresses , so your private
109+
replies have to go through their platform (unless you happen to know the
110+
email address of the user.)
111+
112+
### How can my script/tool send automatic messages?**
113+
114+
In case you want to [create a new
115+
post/topic](https://docs.discourse.org/#tag/Posts/paths/~1posts.json/post)
116+
automatically from a script or tool, you can use the
117+
[Discourse API](https://docs.discourse.org/).
118+
119+
### Who are the admins for Discourse?
120+
121+
See https://llvm.discourse.group/about
122+
123+
### What is the reason for the migration?
124+
125+
**TODO:** add more explanation here
126+
127+
See also
128+
[this email](https://lists.llvm.org/pipermail/llvm-dev/2021-June/150823.html)
129+
130+
### How do I set up a private mailing list?
131+
132+
If needed categories can have individual [security
133+
settings](https://meta.discourse.org/t/how-to-use-category-security-settings-to-create-private-categories/87678)
134+
to limit visibility and write permissions. Contact the
135+
[admins](https://llvm.discourse.group/about) if you need such a category.
136+
137+
### What will happen to our email archives?
138+
139+
**TODO:** Explain the migration.
140+
141+
**TODO:** Can we preserve the links to the email archive?
142+
see [#46](https://github.com/llvm/llvm-iwg/issues/46)
143+
144+
### How Do I cross-post (send in multiple categories) a message?
145+
146+
Topics are assigned to exactly one category, assigning to multiple categories
147+
[is not supported](https://meta.discourse.org/t/selecting-multiple-category/116827).
148+
149+
**TODO:** The documentation says tags can be used to achieve a similar outcome.
150+
However they don't say how to do that.
151+
152+
### I have another question not covered here. What should I do?
153+
154+
Please contact [email protected] or raise a
155+
[ticket on GitHub](https://github.com/llvm/llvm-iwg/issues).

0 commit comments

Comments
 (0)