Communication guidelines

COMMUNICATING.md

@@ -0,0 +1,123 @@
+Communicating within SkyPy
+==========================
+
+Overview
+--------
+
+### Purpose of this Document
+
+This document is intended to specify how information should be communicated within the SkyPy project, to try and ensure:
+  - Messages arrive in a timely way
+  - Messages are visible to all relevant parties
+  - Messages are not unneccessarily duplicated
+  - Messages are not missed
+
+We will provide an overview of the guidelines, followed by specfic guidance for different platforms.
+
+### List of Available Communication Channels
+
+  1. [SkyPyProject Github](https://github.com/skypyproject/) (public)
+  2. SkyPy Slack (private)
+      - Channels
+      - Direct messages
+      - Voice and video calls
+  3. [SkyPy Google Group mailing list](https://groups.google.com/forum/#!forum/skypy) (private)
+  4. SkyPy Zoom Open Office (private)
+  5. SkyPy Google Docs comments (private)
+
+
+### Suggested Order of Preference
+
+We suggest the below prder of preference for communicating within SkyPy. Before sending a message, please think about whether you could send it in a form higher up the list.
+
+  1. Public Github Issue
+  2. Slack channel
+  3. Slack direct message
+
+### Voice and Video vs Written
+
+Voice and video communication has the signficant benefit of allowing communication of tone, but also means the communication is not (by default) recorded for later visibility, and response is required immediately. We encourage voice and video communication whenever appropriate, but please bear in mind these caveats.
+
+Usage of Github
+----------------
+
+### Subscribing to Alerts
+
+Github can provide you with alerts when relevant thinks happen within the SkyPy Organisation on Github:
+  - Comments on Pull Requests and Issues
+  - Pull Request reviews
+  - Pull Request pushes
+
+Each Issue and Pull Request has a **Notifications** area on the right hand side where you may manage notifications for that item. You can also manage what notifications you recieve, and how you recieve them, [here](https://github.com/settings/notifications).
+
+You can also join the #github-notifications channel, or make use of the GitHub bot, on the SkyPy Slack.
+
+### Issues
+
+Github Issues can be opened to communicate about topics within SkyPy **related and un-related to code**. The list of open issues is available [here](https://github.com/skypyproject/skypy/issues) and the comments section within each Issue should be the first place you look to communicate about SkyPy.
+
+If you wish to open a new Issue to discuss a new topic:
+
+  1. Go to the [SkyPy GitHub Repository](https://github.com/skypyproject/skypy)
+  2. Click on the **Issues** tab followed by the **New issue** button
+  3. If an appropriate template exists, click on its **Get started** button
+  4. Otherwise click the **Open a blank issue** link at the bottom of the list
+  5. Clearly describe your issue, including all information requested in the template, if available
+  6. Assign the Issue to yourself and any other relevant SkyPy team members using the area on the right hand side
+  7. If the Issue is covered by any of the available [labels](https://github.com/skypyproject/skypy/issues/labels) add these on the right hand side
+  8. If the Issue is covered by any of the available [SkyPy projects](https://github.com/skypyproject/skypy/projects) add these on the right hand side
+  9. If the Issue relates to a particular SkyPy milestone add this on the right hand side
+  10. If the Issue relates to an open pull request add this on the right hand side
+  11. Click **Submit new issue**
+
+
+### Pull Request Comments
+
+Open Pull Requests also have a **Comments** area which should be used to communicate on topics related to the Pull Request, including comments from the code review.
+
+### Draft Pull Requests
+
+[Draft pull requests](https://github.blog/2019-02-14-introducing-draft-pull-requests/) are pull requests which contain a rough draft of code, which may only express an idea you wish to discuss with other SkyPy members. Others may then contribute on the idea and the code, contributing to how it takes shape. We recommend that Issues should take priority as a way of discussing ideas over Draft Pull Requests, but they may be appropriate where the idea involves details of code or documentation. Note Draft Pull Requests can be associated with Issues.
+
+Usage of Slack
+--------------
+
+### Channels
+
+Channels on the SkyPy slack (e.g. #general) can be used to discuss things relevant to SkyPy which cannot be discussed via Github Issues. Open channels should be used in preference to Slack Direct Messages, in order that other SkyPy members can see and potentially contribute to discussions.
+
+The `@channel` tag will send a notification to all members of the channel, but you may prefer to use `@here` which sends a notification to all members of the channel **who are currently online**.
+
+### Direct Messages
+
+Slack allows for both one-to-one and group Direct Messages, which are not visible to those outside the converation.
+
+### Voice and Video Calling
+
+Slack also has the facility for voice and video calling, both one-to-one and group, which can easily be accessed fro within the app.
+
+Usage of Zoom
+-------------
+
+### Virtual Open Office
+
+A Zoom line is open at all times for use by SkyPy members as a virtual office. It is an appropriate place for voice and video discussions, where those on the call are happy that others may dial in. Think of it like a communcal office with an open door.
+
+In particular the time from 12:00 to 18:00 BST on Tuesday afternoons is available for SkyPy members to attend the virtual open office.
+
+### Organisation Telecons
+
+We organise regular telecons with a cadence of around two weeks. These are organised using the #telecons channel on the SkyPy Slack and also advertised on the #general channel.
+
+
+Usage of Google Group
+---------------------
+
+### Mailing List
+
+Usage of Google Docs
+--------------------
+
+### Draft Documents
+
+### Archived Documents