From 352c49ca9479f44ba60c75f5eb63a5d362105dce Mon Sep 17 00:00:00 2001 From: Giacomo Leidi Date: Fri, 7 Jan 2022 23:49:36 +0100 Subject: [PATCH] Rewrite README.md. (#125) * Rewrite README.md. This patch moves most information about the internals of mobilizon-reshare to the manual to keep the README light and easy to follow. --- README.md | 130 ++++++++++---------------------------------- doc/contributing.md | 27 +++++++++ doc/manual.md | 92 +++++++++++++++++++++++++++++++ 3 files changed, 149 insertions(+), 100 deletions(-) create mode 100644 doc/contributing.md create mode 100644 doc/manual.md diff --git a/README.md b/README.md index b660d5c..85dee37 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,59 @@ [![CI](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/actions/workflows/main.yml) -The goal of mobilizon_reshare is to provide a suite to reshare Mobilizon events on a broad selection of platforms. This +The goal of `mobilizon_reshare` is to provide a suite to reshare Mobilizon events on a broad selection of platforms. This tool enables an organization to automate their social media strategy in regards to events and their promotion. # Usage +## Scheduling and temporal logic + +The tool is designed to work in combination with a scheduler that executes it at +regular intervals. `mobilizon_reshare` allows fine-grained control over the logic to decide when +to publish an event, with the minimization of human effort as its first priority. + ## Installation -mobilizon-reshare is distributed through Pypi. Use +`mobilizon_reshare` is distributed through Pypi and DockerHub. Use -```pip install mobilizon-reshare``` +```shell +$ pip install mobilizon-reshare +``` to install the tool in your system or virtualenv. This should install the command `mobilizon-reshare` in your system. Use it to access the CLI and discover the available commands and their description. -## Scheduling and temporal logic +### Guix package -The tool is designed to work in combination with a scheduler that executes it at -regular intervals. mobilizon_reshare allows fine-grained control over the logic to decide when -to publish an event, with the minimization of human effort as its first priority. +If you run the Guix System you can install `mobilizon_reshare` by running: -## Configuration +``` shell +$ guix install -L . mobilizon-reshare.git +``` -The configuration is implemented through Dynaconf. It allows a variety of ways to specify configuration keys. -Refer to their [documentation](https://www.dynaconf.com/) to discover how configuration files and environment variables can be specified. +To use the same dependencies used in CI env: -We provide a sample configuration in the -[settings.toml](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/blob/master/mobilizon_reshare/settings.toml) file and -[.secrets.toml](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/blob/master/mobilizon_reshare/.secrets.toml) file. +``` shell +$ guix time-machine -C channels-lock.scm -- install -L . mobilizon-reshare.git +``` -Use these files as the base for your custom configuration. +## Run on your local system -### Publishers and notifiers +Once you have installed `mobilizon_reshare` you can schedule the refresh from Mobilizon with your system's `cron`: -The first step to deploy your custom configuration is to specify the source Mobilizon instance and group and then -activate the publishers and notifiers you're interested in. For each one of them, you have to specify credentials and -options in the .secrets.toml file. +```bash +$ sudo crontab -l +*/15 * * * * mobilizon-reshare start +``` -### Publishing strategy - -The second important step is to define when and how your posts should be published. `mobilizon-reshare` takes over the -responsibility of deciding *what* and *when* to publish, freeing the humans from the need to curate the social media -strategy around your events. This might mean very different things for different users and covering common use cases is -a goal of this project. To do so though, you need to guide the tool and understand in detail the options available to -configure it in accordance to the requirements of your desired social media strategy. - -The first option you want to edit is -`publishing.window` that defines the `begin` and `end` hours of your publication window. This means the time frame during the -day in which the tool will consider to publish events. If `begin`>`end`, the window will be overnight -(i.e `begin=19 end=11`, means the tool will publish from 7PM until 11 AM). For now, the hours taken into consideration -are in the server's timezone. - -A second important element is the selection strategy. This is the way the tool will decide which event to pick and -publish among all those available. At every execution of `mobilizon-reshare` will publish at most one event so you have -to consider how the selected strategy will interact with the external scheduling. The strategies assume that the -schedule will fire at regular intervals, unless specified otherwise. These intervals can vary but they should be small -compared to the publishing window. Ideally a few minutes to a couple hours. - -Currently only one strategy is supported: `next_event`. The semantic of the strategy is the following: pick the next -event in chronological order that hasn't been published yet and publish it only if at least -`break_between_events_in_minutes` minutes have passed. - -## Recap - -In addition to the event publication feature, `mobilizon-reshare` allows you to do periodical recap of your events. -In the current version, the two features are handled separately and triggered by different CLI commands (respectively -`mobilizon-reshare start` and `mobilizon-reshare recap`). - -The recap command, when executed, will retrieve the list of already published events and summarize in a single message -to publish on all the active publishers. At the moment it doesn't support any decision logic and will always publish -when triggered. - -## Core Concepts - -### Publisher - -A Publisher is responsible publishing an event or a message on a given platform. - -Currently the following publishers are supported: - -* Telegram -* Zulip -* Twitter - -### Notifier - -Notifiers are similar to Publishers and share most of the implementation. Their purpose is to -notify the maintainers when something unexpected happens. - -### Formatter - -A formatter is responsible for the formatting and validation of an event or a message on a given platform. -Different platform require different templates and rules and therefore formatting is considered a platform-specific -issue. - -### Publication Strategy - -A Publication Strategy is responsible for selecting the event to publish. Currently it's possible to publish only one -event per run, under the assumption that the user will implement a social media strategy that doesn't require -concurrent publishing of multiple events on the same platform. Through proper scheduling and configuration is still -possible to achieve such behavior if required. - -### Coordinator - -A coordinator is responsible for publishing a message or an event across different platforms using different logics. -It uses publishers and formatters to compose and send the message and compile a report of how the publication went. - -## Develop - -To run pre-commit hooks run `pre-commit install` after cloning the repository. - -Make sure to have `pre-commit` installed in your active python environment. To install: `pip install pre-commit`. For more info: https://pre-commit.com/ - -### Testing - -To test, run `poetry install` and then `poetry run pytest` to execute the unit tests. - -At the moment no integration test is present and they are executed manually. Reach out to us if you want to -access the testing environment or you want to help automate the integration tests. +## Deploying through Docker Compose +To run `mobilizon_reshare` in a production environment you can use the image published to DockerHub. We also provide an example [`docker-compose.yml`](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/blob/master/docker-compose.yml). +The image *runs with root privileges*, since they are required to run cron. Right now it # Contributing -We welcome contributions from anybody. Currently our process is not structured yet but feel free to open or take issues through Github in case you want to help us. +We welcome contributions from anybody. Currently our process is not structured but feel free to open or take issues through Github in case you want to help us. We have setup some instructions to setup a development environment [here](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/blob/master/doc/contributing.md). diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000..e41938f --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,27 @@ +# Contributing +## Develop + +To run pre-commit hooks run `pre-commit install` after cloning the repository. + +Make sure to have `pre-commit` installed in your active python environment. To install: `pip install pre-commit`. For more info: https://pre-commit.com/. + +To install dependencies you can either use [Guix](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/blob/master/doc/development-environment-with-guix.md) or poetry: + +```shell +$ poetry install +Installing dependencies from lock file + +Package operations: 44 installs, 0 updates, 0 removals + +[...] + +Installing the current project: mobilizon-reshare (0.1.0) +$ +``` + +### Testing + +To run the test suite, run `poetry run pytest` to execute the unit tests. + +At the moment no integration test is present and they are executed manually. Reach out to us if you want to +access the testing environment or you want to help automate the integration tests. \ No newline at end of file diff --git a/doc/manual.md b/doc/manual.md new file mode 100644 index 0000000..6ba568d --- /dev/null +++ b/doc/manual.md @@ -0,0 +1,92 @@ +# Manual + +## What is mobilizon-reshare? + +`mobilizon_reshare` is a Python application to publish events from Mobilizon on a broad selection of platforms. +This tool enables an organization to automate their social media strategy in regards to events and their promotion. + +## Configuration + +The configuration is implemented through Dynaconf. It allows a variety of ways to specify configuration keys. +Refer to their [documentation](https://www.dynaconf.com/) to discover how configuration files and environment variables can be specified. + +We provide a sample configuration in the +[settings.toml](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/blob/master/mobilizon_reshare/settings.toml) file and +[.secrets.toml](https://github.com/Tech-Workers-Coalition-Italia/mobilizon-reshare/blob/master/mobilizon_reshare/.secrets.toml) file. + +Use these files as the base for your custom configuration. + +### Publishers and notifiers + +The first step to deploy your custom configuration is to specify the source Mobilizon instance and group and then +activate the publishers and notifiers you're interested in. For each one of them, you have to specify credentials and +options in the .secrets.toml file. + +### Publishing strategy + +The second important step is to define when and how your posts should be published. `mobilizon-reshare` takes over the +responsibility of deciding *what* and *when* to publish, freeing the humans from the need to curate the social media +strategy around your events. This might mean very different things for different users and covering common use cases is +a goal of this project. To do so though, you need to guide the tool and understand in detail the options available to +configure it in accordance to the requirements of your desired social media strategy. + +The first option you want to edit is +`publishing.window` that defines the `begin` and `end` hours of your publication window. This means the time frame during the +day in which the tool will consider to publish events. If `begin`>`end`, the window will be overnight +(i.e `begin=19 end=11`, means the tool will publish from 7PM until 11 AM). For now, the hours taken into consideration +are in the server's timezone. + +A second important element is the selection strategy. This is the way the tool will decide which event to pick and +publish among all those available. At every execution of `mobilizon-reshare` will publish at most one event so you have +to consider how the selected strategy will interact with the external scheduling. The strategies assume that the +schedule will fire at regular intervals, unless specified otherwise. These intervals can vary but they should be small +compared to the publishing window. Ideally a few minutes to a couple hours. + +Currently only one strategy is supported: `next_event`. The semantic of the strategy is the following: pick the next +event in chronological order that hasn't been published yet and publish it only if at least +`break_between_events_in_minutes` minutes have passed. + +## Recap + +In addition to the event publication feature, `mobilizon-reshare` allows you to do periodical recap of your events. +In the current version, the two features are handled separately and triggered by different CLI commands (respectively +`mobilizon-reshare start` and `mobilizon-reshare recap`). + +The recap command, when executed, will retrieve the list of already published events and summarize in a single message +to publish on all the active publishers. At the moment it doesn't support any decision logic and will always publish +when triggered. + +## Core Concepts + +### Publisher + +A Publisher is responsible publishing an event or a message on a given platform. + +Currently the following publishers are supported: + +* Telegram +* Zulip +* Twitter + +### Notifier + +Notifiers are similar to Publishers and share most of the implementation. Their purpose is to +notify the maintainers when something unexpected happens. + +### Formatter + +A formatter is responsible for the formatting and validation of an event or a message on a given platform. +Different platform require different templates and rules and therefore formatting is considered a platform-specific +issue. + +### Publication Strategy + +A Publication Strategy is responsible for selecting the event to publish. Currently it's possible to publish only one +event per run, under the assumption that the user will implement a social media strategy that doesn't require +concurrent publishing of multiple events on the same platform. Through proper scheduling and configuration is still +possible to achieve such behavior if required. + +### Coordinator + +A coordinator is responsible for publishing a message or an event across different platforms using different logics. +It uses publishers and formatters to compose and send the message and compile a report of how the publication went.