Skip to main content

​
Before you start

Read the Tech crash course in the README first. Make sure you know what Rosie, Jarbas, and the toolbox do before writing any code.
Serenata de Amor has a 700+ member tech community. Join the conversation on Discord or open a thread in GitHub Issues — both are good places to ask questions and find work to do.

​
Installing

The project uses Docker Compose to standardize the local setup. Every service starts from a single command.
1

Copy the environment file

cp contrib/.env.sample .env
The .env file you just copied contains environment variables for Jarbas. Feel free to customize it — see Jarbas settings for details.
2

Start all services

docker-compose up
docker-compose up is a health check that confirms all dependencies are installed and the project is running. Running Rosie and Jarbas properly requires a few more steps — migrations, data loading, and so on — covered below.

​
Running Rosie

To run only the Rosie AI analysis pipeline: 
docker-compose run --rm rosie python rosie.py run chamber_of_deputies
Rosie downloads the latest open datasets, runs all machine learning classifiers, and produces a suspicions.xz output file.

​
Running Jarbas

Run the Django web server with sample data in the following order:
1

Apply database migrations

docker-compose run --rm django python manage.py migrate
2

Seed sample data

docker-compose run --rm django python manage.py reimbursements /mnt/data/reimbursements_sample.csv
docker-compose run --rm django python manage.py companies /mnt/data/companies_sample.xz
docker-compose run --rm django python manage.py suspicions /mnt/data/suspicions_sample.xz
docker-compose run --rm django python manage.py searchvector
docker-compose run --rm django python manage.py tweets
3

Start the web server

docker-compose up django
Browse to http://0.0.0.0:8000.

​
The basics of contributing

Ideas and discussions happen in GitHub Issues. Browse open issues to find something to work on or propose a new idea. The core team tracks ongoing work on Trello.

​
Git workflow

Follow these seven steps to contribute code:
1

Fork the repository

Click the Fork button in the top-right corner of the GitHub repository.
2

Clone your fork

git clone http://github.com/<YOUR-GITHUB-USERNAME>/serenata-de-amor.git
3

Create a feature branch

git checkout -b <YOUR-GITHUB-USERNAME>-new-stuff
Branch names must be prefixed with your GitHub username. This helps the team track who is working on what.
4

Write your code

Make your changes, add tests where appropriate, and verify that existing tests still pass.
5

Commit your changes

git commit -am 'My pretty cool contribution'
6

Push to your fork

git push origin <YOUR-GITHUB-USERNAME>-new-stuff
7

Open a pull request

Go to your fork on GitHub. A button to open a pull request against the main repository will appear at the top of the page.

​
Branch naming convention

Every branch must start with your GitHub username followed by a short description: 
username-short-description
Examples: 
cuducos-fix-receipt-download
irio-add-senate-classifier
This convention helps maintainers keep track of changes and quickly identify who is working on a given branch.

​
Getting help

Discord community

Join the 700+ member community for questions and real-time discussion.

GitHub Issues

Browse open issues for ideas or report bugs and feature requests.

Build docs developers (and LLMs) love

Get started for freeTalk to us