From 10b3ec5be7aca586a53388fdd7c2c029bdedcd02 Mon Sep 17 00:00:00 2001 From: maike Date: Sun, 5 Jul 2020 18:54:50 +0200 Subject: [PATCH] [misc] Add contribution guidelines --- CONTRIBUTE.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 24 ++++++++++- 2 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTE.md diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..66058e9 --- /dev/null +++ b/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//`: + - `bot.py` + - `model.py` + - `webapi.py` +2. Import your bot in `kibicara/webapi/__init__.py`. + +### Explanation + +In `kibicara/platforms//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//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//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`. + diff --git a/README.md b/README.md index 93fc6cf..cbeab8e 100644 --- a/README.md +++ b/README.md @@ -1 +1,23 @@ -# kibicara \ No newline at end of file +# 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. +