[misc] Add contribution guidelines

CONTRIBUTE.md

@@ -0,0 +1,112 @@
+# Kibicara Contribution Guidelines
+
+## Setup Development Environment
+
+1. Install `python>=3.7`
+2. Create a virtual environment with `python3 -m venv .venv`
+3. Activate your dev environment with `source .venv/bin/activate`
+4. Install with `pip install .`
+5. Install development dependencies with `pip install tox black`
+
+### Build and Test Cycle
+
+- Install with `pip install .`
+- Execute with `kibicara`
+- Interact with Swagger REST-API Documentation: http://localhost:8000/docs
+- Test and stylecheck with `tox`
+- Fix style issues with `black -S kibicara tests`
+
+## Branches
+
+- **Master:** The master branch tracks the last stable release.
+  - Releases will be done using release tags.
+  - Force push and pushes without group consent are disallowed.
+  - There never should be a merge commit from development into master!
+- **Development:** The development branch is used to add new features.
+  - Only rebase of feature branches is allowed.
+  - On Release the development branch will be rebased onto master and a release
+    tag will be created on master
+- **Feature-Branches:**
+  - A feature branch will be used to develop a feature. 
+  - It belongs to one developer only and force push is allowed.
+  - A rebase onto development is necessary to merge the feature. Code reviews
+    are encouraged.
+
+## Write Tests
+
+We use [pytest](https://docs.pytest.org/en/stable/) as a test engine. It is 
+executed by `tox`, so you need to run `tox` on the command line to run the tests.
+
+## Commit Messages
+
+Commits should define small components. Please write your commits with the
+following pattern: 
+
+`[core] Add censor for filtering messages #1312`
+
+Use these:
+- [core] Feature for Kibicara core
+- [frontend] Feature for Kibicara frontend
+- [platform] Feature for platforms like Twitter, Telegram, ...
+- [tests] Tests
+- [misc] e.g. github action files
+- #\d+ if commit is related to specific issues or merge requests
+
+## Comments
+
+### Python
+
+We use pdoc3, which takes prose and comments automatically from the docstrings
+in the repository.
+
+Use [google
+style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)
+comments to secure correct display of your docstrings.
+
+## Merge Requests
+
+The main development team does not need to make merge requests.
+
+If you open a merge request, please include a description which explains the
+improvement.
+
+### Code reviews
+
+Before a merge request gets merged into master, at least one person has to
+approve it; this also increases the number of people who know the code. So
+please request a review from someone from the core development team.
+
+## Implement a new Platform/Social Network
+
+### tl;dr
+
+1. Implement the following modules in `platforms/<your-platform>/`:
+  - `bot.py`
+  - `model.py`
+  - `webapi.py`
+2. Import your bot in `kibicara/webapi/__init__.py`.
+
+### Explanation
+
+In `kibicara/platforms/<your-platform>/bot.py`, you write the functions through 
+which the platform asks the social network for new messages, and publishes 
+messages to the social network. You need to inherit the bot from the `Censor` 
+class at `kibicara/platformapi.py`.
+
+In `kibicara/platforms/<your-platform>/model.py`, you define a database layout. 
+You will probably need to store the following things:
+
+* authentication credentials,
+* timestamps/IDs of the last seen message,
+* platform-specific settings
+* anything else your platform needs
+
+In `kibicara/platforms/<your-platform>/webapi.py`, you can define HTTP routes. 
+You will need them to:
+
+* let admins authenticate to the social network in the kibicara web interface
+* update platform-specific settings 
+
+To run the platform, you need to import the bot in
+`kibicara/webapi/__init__.py`.
+

README.md

@@ -1 +1,23 @@
-# kibicara
+# Kibicara
+
+Kibicara relays messages between different platforms (= social networks).
+
+In its web interface, a hood admin (= registered user) can create a hood to
+build a connection between different platforms. 
+
+Users can message a specific hood account on a specific platform (e.g. @xyz on
+Telegram). This pushes the announcement to all platform accounts of a hood.
+For example: User A writes a message to @xyz on Telegram (which has been
+connected to Kibicara by a hood admin). This publishes the message on e.g.
+Twitter and other platforms which have been connected to the hood.
+
+The admin of a hood has to define trigger words and bad words. Messages need to
+contain a trigger word to be relayed, and must not contain a bad word.
+
+Kibicara needs to be hosted on a server by an instance maintainer. That way,
+hood admins don't need a server of their own.
+
+## Contribute!
+
+Read `CONTRIBUTE.md` to learn how to get started.
+