The MousikóFídi developer's guide!
All development should be done on the
dev branch. To contribute a patch to MousikóFídi:
Fork the main repository, check out the
Create a branch named loosely after the work being done (e.g.
my-cool-feature, but don't get too crazy)
Make changes, run tests (see below for more information about creating and running tests)
Wiki content lives on the
- Wiki content lives on the
- Write tests as needed, run tests
- Commit your changes
- Send in your patch!
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:
This is of course useful when working on the codebase.
→ pre-commit hook
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:
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:
.cssfile that will represent your theme's styling in the
mousikofidi/static/cssdirectory of the MousikóFídi code repository. Give it a distinct name that represents the theme well.
Then, add your theme to the
THEMESdict 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.
→ Creating A New Holiday Logo
To add a new date-based "holiday" logo to MousikóFídi:
Create the logo file and place it into the
mousikofidi/staticdirectory 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.
Add the logo to the
LOGOSdict in the main MousikóFídi python file.
The format is:
"date conditional": "file-name.png"
date_conditionalcan me a specific
month-daystring, such as
Or, it can be a specific day or month:
A full example:
- The format is:
Tests should accompany any new features or fixes as needed.
Please always run tests before making a commit.
Python code should be formatted with Python Black. This is checked as part of the test process when any one of
make test-quiet, or
make test-verbose are ran.
Also available are the
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
All tests for the Python code in MousikóFídi are driven by
pytest package is installed as part of the dev setup process above.
All tests against Python and HTML code are done here.
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.)
→ 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
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
Once you've built the site, you can run
make serve to start a python-based simple HTTP server for viewing your local website.