From 88353bc9235b3fc30b352d540215346b16fddba3 Mon Sep 17 00:00:00 2001 From: Will Hunt <will@half-shot.uk> Date: Sat, 11 May 2019 22:49:27 +0100 Subject: [PATCH] Add contributing --- CONTRIBUTING.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c3f0895 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,90 @@ +Hello! It's awesome that you want to contribute to the Discord bridge, by doing +so you are helping our users and the wider Matrix ecosystem. This document +lists the requirements for your work to be accepted into our repository. + +For clarity reasons, work can either be a pull request or an issue. We find +both quite valuable to the project. Please note that your work must abide by +the Apache 2 license found in the LICENSE file. + +Most importantly we are a welcoming project and will be happy to review any +works, no matter the skill level of the submitter. Everyone must start +somewhere! + +## TL;DR + +* Always work off the **develop** branch. We won't accept merges into any other branches. + +* We follow the [Matrix Code of Conduct](https://matrix.org/docs/guides/code_of_conduct.html) and will not accept or entertain works from individuals who break it. We believe in considerate and respectful members above accepting works, regardless of quality. + * This includes possible bans from any room(s) involved with the project. +* We are limited to accepting work over Github. Please use its interface when submitting work items. +* Discussion of ideas for the bridge and work items should be in [#discord:half-shot.uk](https://matrix.to/#/#discord:half-shot.uk). +* Everything submitted as a PR should have at least one test, the only exception being non-code items. + +## Overview of the Bridge + +The bridge runs as a standalone server that connects to both the Discord API +network and a local Matrix homeserver over the [application service +protocol](https://matrix.org/docs/spec/application_service/unstable.html). +Primarily it syncs events and users from Matrix to Discord and vice versa. + +While the bridge is constantly evolving and we can't keep this section updated +with each component, we follow the principle of handler and processor classes +and each part of the functionality of the bridge will be in a seperate class. +For example, the processing of Matrix events destined for Discord are handled +inside the `MatrixEventProcessor` class. + +## Setting up + +(This section needs to be written in detail) + +* You will need to [setup the bridge](https://github.com/Half-Shot/matrix-appservice-discord/tree/develop#setup-the-bridge) similarly to how we describe, + but you should setup a homeserver locally on your development machine. We would recommend [Synapse](https://github.com/matrix-org/synapse#id11). + +## Writing an issue + +When writing an issue, please be as verbose as you can. Remember the issue is +there to either document a feature request, or report a bug so it can be fixed. +The issue board is NOT there to complain about a broken or missing feature. + +We leave it to the author's discretion to decide what to include rather than +provide a template, but good items are: + * Shorter titles are better than long rambling ones, but please don't make it too vague. + * A good example is "Ability to bridge an existing matrix room into a discord channel" + * A brief description of the problem. + * If you are a user of another person's bridge, please can you let us know the name of the service provider. + * If you would like to keep the details private, please PM @Half-Shot:half-shot.uk discreetly. + * Relevant logging from Synapse/your homeserver AND the bridge (if applicable). + * The more verbose, the better but please don't include sensitive details like access tokens. + * A screenshot is always useful. + * Please mention which direction a failure is in, e.g. Matrix -> Discord, if applicable. + +We will assign each issue a tag, which will allow us to categorise the problems. + +While we realise some issues are more important than others, please do not "demand" +for an issue to be fixed. Issues will be worked on in the timeframe that best fits +the needs of the team. + + +## PR Process + +We've tried our best to keep the PR process relatively simple: + +* Create a new branch based off the `develop` branch. + * This can be done with `git checkout develop` followed by `git checkout -b featurename`. +* Create a PR on Github, making sure to give a brief discription of your changes and link to the issue it fixes, if any. + * If your change is not complete but you would like feedback, create it as a draft. +* Ensure the linter and tests are not failing, as we will not accept code that breaks either. + * If your tests fail and are having trouble fixing them, you may push your changes and we will help you fix them. + * Github automatically pokes TravisCI to run both linting and tests. +* Someone from the team will review your work and decide what to do with the PR. + * Usually we will have feedback for the PR and will submit more comments. + * We may decide to reject it, if a feature has little chance of fitting in with the project goals. + +## Testing + +Testing the bridge is easy enough, you just need to run `npm run build`, +`npm run lint` and `npm run test`. If all pass without errors, congratulations! + +Please bear in mind that you will need to cover the whole, or a reasonable +degree of your code. You can check to see if you have with `npm run +coverage`. -- GitLab