Developer's Guide

The MousikóFídi developer's guide!

→ Contributing

All development should be done on the dev branch. To contribute a patch to MousikóFídi:

  1. Fork the main repository, check out the dev branch.
  2. Create a branch named loosely after the work being done (e.g. my-cool-feature, but don't get too crazy)
  3. Make changes, run tests (see below for more information about creating and running tests)
  4. Write tests as needed, run tests
  5. Commit your changes
  6. Send in your patch!

Subscribe and post to the MousikóFídi mailing list here, and you can hop onto the IRC channel from any instance's /about page or by directly joining #mousikofidi on irc.freenode.net.

→ Setup

To get set up for development, first install the required dependencies: 

cd /path/to/mousikofidi
# Optionally use the --user flag if desired
pip3 install -r requirements.txt
pip3 install -r dev-requirements.txt

Run the tests once just to be sure you're in a good spot: 

cd /path/to/mousikofidi
make tests  # tests-quiet or tests-verbose are also available

Then hack away! You can run the dev server like this: 

make dev-server

This is of course useful when working on the codebase.

→ pre-commit hook

The pre-commit.sh script within this repo is meant to function as a pre-commit hook.

It can be installed via make githooks, but this also happens automatically when make dev-requirements and make test (and variants) are ran.

Installation can also be done by manually invoking the script: 

/path/to/pre-commit.sh --install

Having this hook installed ensures that commits will not break tests and is essential for working with the MousikóFídi codebase.

→ Creating A New CSS Theme

Adding a new CSS theme to MousikóFídi is a relatively simple process:

  1. Create the .css file that will represent your theme's styling in the mousikofidi/static/css directory of the MousikóFídi code repository. Give it a distinct name that represents the theme well.
  2. Then, add your theme to the THEMES dict in the main MousikóFídi python file. Follow the format of the existing themes; give your theme's name and the path to the file minus the extension.

To add a new date-based "holiday" logo to MousikóFídi:

  1. Create the logo file and place it into the mousikofidi/static directory of the MousikóFídi code repository. Give it a distinct name that represents the holiday or idea behind it well. Whatever you want, really.
  2. Add the logo to the LOGOS dict in the main MousikóFídi python file.
    • The format is: "date conditional": "file-name.png"
    • The date_conditional can me a specific month-day string, such as 05-01
    • Or, it can be a specific day or month: day:01, month:05
    • A full example: "05-01": "file-name.png"

→ Tests

Tests should accompany any new features or fixes as needed.

Please always run tests before making a commit.

→ Style

Python code should be formatted with Python Black. This is checked as part of the test process when any one of make test, make test-quiet, or make test-verbose are ran.

Also available are the make test-black, make test-black-quiet, and make test-black-verbose targets.

→ Flake 8

Also ran with tests are flake8 checks. The flake8 package is installed as part of the dev setup process above.

Before tests can pass, a ~/.config/flake8 file must exist on your system and it must include the below lines at minimum: 

[flake8]
ignore = E501, E402, W503
max-line-length = 160

→ Pytest

All tests for the Python code in MousikóFídi are driven by pytest. The pytest package is installed as part of the dev setup process above.

All tests against Python and HTML code are done here.

→ Javascript

The MousikóFídi project aims to only use vanilla Javascript.

Additionally, any Javascript code should have tests. All Javascript tests are executed on the test_js.html template, which is viewable at the /test-js route on any instance (note, the tests only work if the example dir is found.)

As of right now, there's no automated process for running these tests, so be sure to check whem when working with the Javascript portion of the codebase.

→ Publishing A Release

A release artifact is published to PyPI via a sourcehut build when a git tag is pushed. This is handled by the pypi-upload.sh script included in the base of the MousikóFídi code repo.

Note that any tag containing the string beta will not be published.

→ Documentation Website

The Documentation Website, https://mousikofidi.info/, exists on the mousikofidi.info branch and is automatically updated any time that branch is updated.

Building requires soupault 2.0.0 or higher, simply switch to the mousikofidi.info branch and run make from the root of the repository. The built website will be placed into a directory called build/.

Once you've built the site, you can run make serve to start a python-based simple HTTP server for viewing your local website.

This page was last modified on: 2020-10-03