The MousikóFídi developer's guide!

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

The main test targets all require a yuicompressor executable to be available on your system.

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.

Contributing

See the free Pro Git book for a great guide on using git. It's also the official guide to git!

To contribute a patch to MousikóFídi:

  1. Fork the main repository
  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.

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. Add your new theme to the minify Makefile targets; simply copy and paste the existing lines there and edit the name of your theme file in (each line has two mentions, the regular file and the .min version). Do this for both the minify and minify-quiet targets.
  3. Add the path to your theme to the minification test script. Simply append your theme's file to the existing list of files.
  4. Finally, 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.

Minified Statics

Minified versions of MousikóFídi CSS and Javascript are shipped with the codebase. These can be generated via the make minify target, which should be done before making any commits with changes to CSS or Javascript.

This is checked as part of the main test targets, but a working installation of yuicompressor is required.

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.

Home Page

The Home Page, or https://mousikofidi.info/, exists on the mousikofidi.info branch and is automatically updated any time that or the wiki branch are updated.

It's built with soupault and generates several pages from the wiki.

About this wiki

commit 0b5536b3d27c8d1c52dfc04e69ffa85fa76ad677
Author: Hristos N. Triantafillou <me@hristos.triantafillou.us>
Date:   2019-11-06T00:04:51+00:00

Link to the home page, not the wiki
Clone this wiki
https://git.sr.ht/~hristoast/mousikofidi (read-only)
git@git.sr.ht:~hristoast/mousikofidi (read/write)