docs/rooms.md

   1 # Rooms
   2
   3 Rooms are part of a community.
   4
   5 Rooms are also referred to as "troupes" internally in the codebase for legacy reasons.
   6
   7 All rooms have unlimited message history, public or private.
   8
   9
  10 ## People/Roster
  11
  12 You can see who is in the room and add/invite new users via the roster section in the right-toolbar
  13
  14 ![](https://i.imgur.com/nW29SY1.png)
  15
  16 #### Eyeballs Disambiguation
  17
  18 Eyeballs are the green and yellow/orange dots on top of the avatars in the people section of a room. They represent the current status or online presence of a person in the room.
  19
  20 ![](https://i.imgur.com/MRuIXK4.png)
  21
  22 So what does each color mean?
  23
  24  - **Green**: Actively looking at the room
  25  - **Yellow/Orange**: Not actively looking at the room
  26
  27 "Actively looking" equates to whether the window has focus and the room is open.
  28
  29
  30
  31 ## Room user
  32
  33 ### Leave a room
  34
  35 You can leave a room via **Room settings dropdown** -> **Leave this room**
  36
  37 If you have mad skillz, you can also type "/leave" in the chat room (slash command).
  38
  39 It's not possible to leave a one to one room, only hide it(see below)
  40
  41 ![](https://i.imgur.com/Rc4EVnV.png)
  42
  43
  44 ### Hide a room
  45
  46 You can hide a room via **Room settings dropdown** -> **Hide this room**
  47
  48 Hiding a room will keep it from appearing in your left-menu room list. If you receive a notification for the room again, it will reappear. If you no longer wish to receive notifications from that room, you should either leave that room (`/leave` slash command) or change notifications to mentions only. You cannot leave a one-to-one room.
  49
  50 ![](https://i.imgur.com/ceIVTNd.png)
  51
  52
  53 ## Room admin
  54
  55 ### Room creation
  56
  57 Use the **+** -> **Create room** option in the bottom-left of the menu bar to start the room creation process.
  58
  59 ![](https://i.imgur.com/Mt6sMOe.png)
  60
  61 If you want to associate the room with a GitLab project or GitHub repo, just select it from the repo dropdown (make sure you are signed in respectively with GitLab or GitHub). If you don't see a GitHub repo listed in the dropdown, see the [FAQ](./faq.md#why-isnt-my-github-organisation-or-repos-appearing)
  62
  63 ![](https://i.imgur.com/yOobB1g.png)
  64
  65
  66 #### Why isn't my GitHub organisation or repos appearing?
  67
  68 See the [FAQ](./faq.md#why-isn-t-my-github-organisation-or-repos-appearing).
  69
  70
  71 ### Room security
  72
  73 **Public rooms**
  74
  75  - A public room can be seen by everyone
  76
  77 **Private rooms**
  78
  79  - A room connected to a private project/repo can be accessed by anyone with access to the project/repo.
  80  - A private room with no association can only be accessed if they are manually invited to the room.
  81  - A private room can also be associated with the community and anyone in the community can join the room. If the community was associated with a group/org, anyone in the group/org could join for example.
  82
  83 #### Change room security after creation
  84
  85 It is currently not possible to adjust your room security (public/private) after creation,
  86 but we can do it manually for you.
  87
  88 Send a message to support@gitter.im with the following info. Make sure to email with the primary email address associated with the GitLab/GitHub/Twitter account tied to your Gitter account.
  89
  90  - Link to the room on Gitter
  91  - New desired public/private security or repo/org association
  92  - Some context behind the change
  93
  94 You can track https://gitlab.com/gitterHQ/webapp/issues/676 for progress on this issue.
  95
  96
  97
  98 ### Room topic/description
  99
 100 A room topic/description will help the community members and new people joining to know what's the purpose of the room.
 101
 102 To set up your room topic, double-click on the area next to the room name in the chat header.
 103
 104 You can also use the `/topic <some topic message>` slash command to set the room topic.
 105
 106 ![](https://i.imgur.com/ecdteoh.png)
 107
 108 ### Room welcome message
 109
 110 You can set a room welcome message via **Room settings dropdown** -> **Settings** -> **Welcome message**. This message is only shown when joining a room and the user needs to click the "I understand" button before joining the room.
 111
 112 ![](https://i.imgur.com/ujd8kHE.png) ![](https://i.imgur.com/06azySl.png) ![](https://i.imgur.com/Sou791K.png)
 113
 114
 115 ### Add a Gitter badge to your repo readme
 116
 117 During room creation, if you add a repo association, you will see a checkbox option **Send PR to add the Gitter badge to your README**, that will automagically have the [Gitter Badger bot](https://github.com/gitter-badger) send a pull request to add the Gitter badge.
 118
 119 If you missed that option during room creation, after the fact, you can go to the **Room settings dropdown** -> **Share this chat room** -> **README badge** and copy the markdown text to put in your own readme.
 120 If your room is associated with a GitHub repo, you can use the **Send pull request** button to have the [Gitter Badger bot](https://github.com/gitter-badger) send a pull request with the badge markdown added.
 121
 122 ![](https://i.imgur.com/LRwMqHk.png)
 123
 124
 125 ### Moderation
 126
 127 As an admin of the room, you can delete messages from other users.
 128
 129 You can add new admins for a room via **Room settings dropdown** -> **Permissions** modal.
 130
 131
 132 ### Restrict room to GitHub users
 133
 134 You can restrict a room to GitHub users via **Room settings dropdown** -> **Settings** -> **Only GitHub users are allowed to join this room.** checkbox.
 135
 136 ![](https://i.imgur.com/ujd8kHE.png) ![](https://i.imgur.com/oOGoEYw.png)
 137
 138
 139 ### Export room data
 140
 141 You can export data associated with your room via **Room settings dropdown** -> **Export room data**.
 142
 143 If you're looking to export data for your own user, see the [account docs on exports](./accounts.md#how-do-i-export-my-data).
 144
 145
 146 ### Rename a room
 147
 148 If you want to rename a room because a GitHub repo was renamed/transferred, see this [FAQ section instead](./faq.md#what-happens-if-i-rename-something-on-GitHub-org-repo) instead.
 149
 150 Currently, there isn't a way to rename a room in the UI. But you can send a message to support@gitter.im with the following info. Make sure to email with the primary email address associated with the GitLab/GitHub/Twitter account tied to your Gitter account.
 151
 152  - Link to the current Gitter room
 153  - Desired room name
 154
 155
 156 ### Delete a room
 157
 158 If you are a room admin, you can delete a room via **Room settings dropdown** -> **Delete this room**.
 159
 160 ![](https://i.imgur.com/FqxWgsM.png)