llvm/docs/DiscourseMigrationGuide.md

   1 # Discourse Migration Guide
   2
   3 This document is intended to help LLVM users to migrate from the mailing lists to
   4 Discourse. Discourse has 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 <table border=1>
  22 <tr><th>Mailing list</th><th>Discourse</th></tr>
  23 <tr><td><i>Mailing list</i>, consists of threads</td><td><i>category</i>, consists of topics</td></tr>
  24 <tr><td><i>thread</i>, consists of emails</td><td><i>topic</i>, consists of posts</td></tr>
  25 <tr><td>email</td><td>post</td></tr>
  26 </table>
  27
  28 ## Setting up email interactions
  29
  30 Some folks want to interact with Discourse purely via their email program. Here
  31 are the typical use cases:
  32
  33 * You can [subscribe to a category or topic](https://discourse.mozilla.org/t/how-do-i-subscribe-to-categories-and-topics/16024)
  34 * You can reply to a post, including quoting other peoples texts
  35   ([tested](https://llvm.discourse.group/t/email-interaction-with-discourse/3306/4) on GMail).
  36 * [Quoting previous topics in an reply](https://meta.discourse.org/t/single-quote-block-dropped-in-email-reply/144802)
  37 * **TODO:** Creating new topics via email is
  38   [supported](https://meta.discourse.org/t/start-a-new-topic-via-email/62977)
  39   but not configured at the moment. We would need to set up an email address
  40   per category and give Discourse POP3 access to that email account. This sounds
  41   like a solvable issue.
  42 * You can filter incoming emails in your email client by category using the
  43   `List-ID` email header field.
  44
  45 ## Mapping of mailing lists to categories
  46
  47 This table explains the mapping from mailing lists to categories in Discourse.
  48 The email addresses of these categories will remain the same, after the
  49 migration.  Obsolete lists will become read-only as part of the Discourse
  50 migration.
  51
  52
  53 <table border=1>
  54 <tr><th>Mailing lists</th><th>Category in Discourse</th></tr>
  55
  56 <tr><td>All-commits</td><td>no migration at the moment</td></tr>
  57 <tr><td>Bugs-admin</td><td>no migration at the moment</td></tr>
  58 <tr><td>cfe-commits</td><td>no migration at the moment</td></tr>
  59 <tr><td>cfe-dev</td><td>Clang Frontend</td></tr>
  60 <tr><td>cfe-users</td><td>Clang Frontend/Using Clang</td></tr>
  61 <tr><td>clangd-dev</td><td>Clang Frontend/clangd</td></tr>
  62 <tr><td>devmtg-organizers</td><td>Obsolete</td></tr>
  63 <tr><td>Docs</td><td>Obsolete</td></tr>
  64 <tr><td>eurollvm-organizers</td><td>Obsolete</td></tr>
  65 <tr><td>flang-commits</td><td>no migration at the moment</td></tr>
  66 <tr><td>flang-dev</td><td>Subprojects/Flang Fortran Frontend</td></tr>
  67 <tr><td>gsoc</td><td>Obsolete</td></tr>
  68 <tr><td>libc-commits</td><td>no migration at the moment</td></tr>
  69 <tr><td>libc-dev</td><td>Runtimes/C</td></tr>
  70 <tr><td>Libclc-dev</td><td>Runtimes/OpenCL</td></tr>
  71 <tr><td>libcxx-bugs</td><td>no migration at the moment</td></tr>
  72 <tr><td>libcxx-commits</td><td>no migration at the moment</td></tr>
  73 <tr><td>libcxx-dev</td><td>Runtimes/C++</td></tr>
  74 <tr><td>lldb-commits</td><td>no migration at the moment</td></tr>
  75 <tr><td>lldb-dev</td><td>Subprojects/lldb</td></tr>
  76 <tr><td>llvm-admin</td><td>no migration at the moment</td></tr>
  77 <tr><td>llvm-announce</td><td>Announce</td></tr>
  78 <tr><td>llvm-branch-commits</td><td>no migration at the moment</td></tr>
  79 <tr><td>llvm-bugs</td><td>no migration at the moment</td></tr>
  80 <tr><td>llvm-commits</td><td>no migration at the moment</td></tr>
  81 <tr><td>llvm-dev</td><td>Project Infrastructure/LLVM Dev List Archives</td></tr>
  82 <tr><td>llvm-devmeeting</td><td>Community/US Developer Meeting</td></tr>
  83 <tr><td>llvm-foundation</td><td>Community/LLVM Foundation</td></tr>
  84 <tr><td>Mlir-commits</td><td>no migration at the moment</td></tr>
  85 <tr><td>Openmp-commits</td><td>no migration at the moment</td></tr>
  86 <tr><td>Openmp-dev</td><td>Runtimes/OpenMP</td></tr>
  87 <tr><td>Parallel_libs-commits</td><td>no migration at the moment</td></tr>
  88 <tr><td>Parallel_libs-dev</td><td>Runtimes/C++</td></tr>
  89 <tr><td>Release-testers</td><td>Project Infrastructure/Release Testers</td></tr>
  90 <tr><td>Test-list</td><td>Obsolete</td></tr>
  91 <tr><td>vmkit-commits</td><td>Obsolete</td></tr>
  92 <tr><td>WiCT</td><td>Community/Women in Compilers and Tools</td></tr>
  93 <tr><td>www-scripts</td><td>Obsolete</td></tr>
  94 </table>
  95
  96
  97 ## FAQ
  98
  99 ### I don't want to use a web UI
 100
 101 You can do most of the communication with your email client (see section on
 102 Setting up email interactions above). You only need to set up your account once
 103 and then configure which categories you want to subscribe to.
 104
 105 ### How do I send a private message?
 106
 107 On the mailing list you have the opportunity to reply only to the sender of
 108 the email, not to the entire list. That is not supported when replying via
 109 email on Discourse. However you can send someone a private message via the
 110 Web UI: Click on the user's name above a post and then on `Message`.
 111
 112 Also Discourse does not expose users' email addresses , so your private
 113 replies have to go through their platform (unless you happen to know the
 114 email address of the user.)
 115
 116 ### How can my script/tool send automatic messages?**
 117
 118 In case you want to [create a new
 119 post/topic](https://docs.discourse.org/#tag/Posts/paths/~1posts.json/post)
 120 automatically from a script or tool, you can use the
 121 [Discourse API](https://docs.discourse.org/).
 122
 123 ### Who are the admins for Discourse?
 124
 125 See https://llvm.discourse.group/about
 126
 127 ### What is the reason for the migration?
 128
 129 See
 130 [this email](https://lists.llvm.org/pipermail/llvm-dev/2021-June/150823.html)
 131
 132 ### How do I set up a private mailing list?
 133
 134 If needed categories can have individual [security
 135 settings](https://meta.discourse.org/t/how-to-use-category-security-settings-to-create-private-categories/87678)
 136 to limit visibility and write permissions. Contact the
 137 [admins](https://llvm.discourse.group/about) if you need such a category.
 138
 139 ### What will happen to our email archives?
 140
 141 The Mailman archives will remain on the web server for now.
 142
 143 ### What are advantages of Discourse over the current mailing lists?
 144
 145 * Users can post to any category, also without being subscribed.
 146 * Full text search on the Web UI.
 147 * Sending/replying via the Web UI (email is still possible).
 148 * View entire thread on one page.
 149 * Categories are a more light-weight option to structure the discussions than
 150   creating new mailing lists.
 151 * Single sign on with GitHub.
 152 * User email addresses are kept private.
 153
 154 ### I have another question not covered here. What should I do?
 155
 156 Please contact iwg@llvm.org or raise a
 157 [ticket on GitHub](https://github.com/llvm/llvm-iwg/issues).