From 645c845d45ae9d92e642b9568807512f68dfc937 Mon Sep 17 00:00:00 2001 From: Tanya Lattner Date: Fri, 7 Jan 2022 20:24:35 -0800 Subject: [PATCH] Add first draft of the discourse migration guide. --- llvm/docs/DiscourseMigrationGuide.md | 157 +++++++++++++++++++++++++++ llvm/docs/index.rst | 4 + 2 files changed, 161 insertions(+) create mode 100644 llvm/docs/DiscourseMigrationGuide.md diff --git a/llvm/docs/DiscourseMigrationGuide.md b/llvm/docs/DiscourseMigrationGuide.md new file mode 100644 index 000000000000..7ae9f6953d43 --- /dev/null +++ b/llvm/docs/DiscourseMigrationGuide.md @@ -0,0 +1,157 @@ +# Discourse Migration Guide + +This document is intended to help LLVM users to migrate from the mailing lists to +Discourse. Discourse has two basic ways for interaction: Via the [web +UI](https://llvm.discourse.group/) and via emails. + +## Setting up your account + +The easiest way is to create an account using your GitHub account: + +1. Navigate to https://llvm.discourse.group/ +1. Click on "Sign Up" in the top right corner. +1. Choose "With GitHub" on the right side and log in with your GitHub account. + +## Structure of Discourse + +Discourse's structure is similar to a set of mailing lists, however different +terms are used there. To help with the transition, here's a translation table +for the terms: + + + + + + +
Mailing listDiscourse
Mailing list, consists of threadscategory, consists of topics
thread, consists of emailstopic, consists of posts
emailpost
+ +## Setting up email interactions + +Some folks want to interact with Discourse purely via their email program. Here +are the typical use cases: + +* You can [subscribe to a category or topic](https://discourse.mozilla.org/t/how-do-i-subscribe-to-categories-and-topics/16024) +* You can reply to a post, including quoting other peoples texts + ([tested](https://llvm.discourse.group/t/email-interaction-with-discourse/3306/4) on GMail). +* [Quoting previous topics in an reply](https://meta.discourse.org/t/single-quote-block-dropped-in-email-reply/144802) +* **TODO:** Creating new topics via email is + [supported](https://meta.discourse.org/t/start-a-new-topic-via-email/62977) + but not configured at the moment. We would need to set up an email address + per category and give Discourse POP3 access to that email account. This sounds + like a solvable issue. +* You can filter incoming emails in your email client by category using the + `List-ID` email header field. + +## Mapping of mailing lists to categories + +This table explains the mapping from mailing lists to categories in Discourse. +The email addresses of these categories will remain the same, after the +migration. Obsolete lists will become read-only as part of the Discourse +migration. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mailing listsCategory in Discourse
All-commitsno migration at the moment
Bugs-adminno migration at the moment
cfe-commitsno migration at the moment
cfe-devClang Frontend
cfe-usersClang Frontend/Using Clang
clangd-devClang Frontend/clangd
devmtg-organizersObsolete
DocsObsolete
eurollvm-organizersObsolete
flang-commitsno migration at the moment
flang-devSubprojects/Flang Fortran Frontend
gsocObsolete
libc-commitsno migration at the moment
libc-devRuntimes/C
Libclc-devRuntimes/OpenCL
libcxx-bugsno migration at the moment
libcxx-commitsno migration at the moment
libcxx-devRuntimes/C++
lldb-commitsno migration at the moment
lldb-devSubprojects/lldb
llvm-adminno migration at the moment
llvm-announceAnnounce
llvm-branch-commitsno migration at the moment
llvm-bugsno migration at the moment
llvm-commitsno migration at the moment
llvm-devProject Infrastructure/LLVM Dev List Archives
llvm-devmeetingCommunity/US Developer Meeting
llvm-foundationCommunity/LLVM Foundation
Mlir-commitsno migration at the moment
Openmp-commitsno migration at the moment
Openmp-devRuntimes/OpenMP
Parallel_libs-commitsno migration at the moment
Parallel_libs-devRuntimes/C++
Release-testersProject Infrastructure/Release Testers
Test-listObsolete
vmkit-commitsObsolete
WiCTCommunity/Women in Compilers and Tools
www-scriptsObsolete
+ + +## FAQ + +### I don't want to use a web UI + +You can do most of the communication with your email client (see section on +Setting up email interactions above). You only need to set up your account once +and then configure which categories you want to subscribe to. + +### How do I send a private message? + +On the mailing list you have the opportunity to reply only to the sender of +the email, not to the entire list. That is not supported when replying via +email on Discourse. However you can send someone a private message via the +Web UI: Click on the user's name above a post and then on `Message`. + +Also Discourse does not expose users' email addresses , so your private +replies have to go through their platform (unless you happen to know the +email address of the user.) + +### How can my script/tool send automatic messages?** + +In case you want to [create a new +post/topic](https://docs.discourse.org/#tag/Posts/paths/~1posts.json/post) +automatically from a script or tool, you can use the +[Discourse API](https://docs.discourse.org/). + +### Who are the admins for Discourse? + +See https://llvm.discourse.group/about + +### What is the reason for the migration? + +See +[this email](https://lists.llvm.org/pipermail/llvm-dev/2021-June/150823.html) + +### How do I set up a private mailing list? + +If needed categories can have individual [security +settings](https://meta.discourse.org/t/how-to-use-category-security-settings-to-create-private-categories/87678) +to limit visibility and write permissions. Contact the +[admins](https://llvm.discourse.group/about) if you need such a category. + +### What will happen to our email archives? + +The Mailman archives will remain on the web server for now. + +### What are advantages of Discourse over the current mailing lists? + +* Users can post to any category, also without being subscribed. +* Full text search on the Web UI. +* Sending/replying via the Web UI (email is still possible). +* View entire thread on one page. +* Categories are a more light-weight option to structure the discussions than + creating new mailing lists. +* Single sign on with GitHub. +* User email addresses are kept private. + +### I have another question not covered here. What should I do? + +Please contact iwg@llvm.org or raise a +[ticket on GitHub](https://github.com/llvm/llvm-iwg/issues). diff --git a/llvm/docs/index.rst b/llvm/docs/index.rst index 7e0bc8c4552b..12e30adae43e 100644 --- a/llvm/docs/index.rst +++ b/llvm/docs/index.rst @@ -57,6 +57,7 @@ Getting Started, How-tos, Developer Guides, and Tutorials. GettingStartedTutorials Reference UserGuides + DiscourseMigrationGuide :doc:`GettingStartedTutorials` For those new to the LLVM system. @@ -67,6 +68,9 @@ Getting Started, How-tos, Developer Guides, and Tutorials. :doc:`Reference` LLVM and API reference documentation. +:doc:`DiscourseMigrationGuide` + Guide for users to migrate to Discourse + Community =========