Skip to content

How to Contribute

Thank you for your interest in contributing to the musical-notes project :heart:. This document lists the most common operations that you may need to contribute.

How does the project work?

Project Structure

flowchart
    . --> docs
    . --> musical_notes
    . --> tests

The project is divided into three directories: docs, musical_notes, and tests, where each directory has its specific function.

musical_notes

flowchart
    . --> musical_notes

    musical_notes --> chords.py 
    musical_notes --> cli.py
    musical_notes --> convert_degrees.py
    musical_notes --> half_step.py
    musical_notes --> harmonic_field.py
    musical_notes --> minors.py
    musical_notes --> scales.py
    musical_notes --> triads.py

The CLI code and library are in musical_notes. The API documentation for the code is also being done in musical_notes. The mkdocstrings tool is being used, following the Google docstrings pattern. So, if you change anything in the code, remember to also update the docstrings.

The examples used in the docstring are also being used for testing. So, if you change the output format, remember to update the docstrings.

The CLI

The CLI was built using the Typer library, and you can check its documentation for more details if you want to expand the CLI's functionalities.

For rich output responses in the application, the Rich library was used. If you want to change anything related to the tables generated in the output, you can go directly to the documentation page for the tables.

Tests

We are using pytest for testing. Its configurations can be found in the pyproject.toml file at the root of our project.

Important things to know about the tests are that not all tests are located in the musical_notes/tests directory. The addopts = "--doctest-modules" flag is being used. So, if you modify anything, be aware that the docstrings also run tests and are the basis for API documentation, so be careful with changes.

Test coverage is automatically generated with pytest-cov and displayed when the test task is executed:

task tests

NOTE:
As well as linters are requirements for these tests.

Documentation

The entire documentation is based on using mkdocs with the mkdocs-material theme.

flowchart
    . --> docs
    . --> mkdocs.yml
    docs --> files.md
    docs --> api
    docs --> assets
    docs --> templates
    docs --> stylesheets

All configuration can be found in the mkdocs.yml file at the root of the repository.

Various devices are also being used to complement the documentation, such as jinja templates where instructions can repeat. If you come across blocks like:

{ %  % }

NOTE:
You will know that it is a template.

The templates are defined in the /docs/templates directory. In some cases, however, they may be called by variables with command.run, which appears in almost all documentation files. These macros are being made with mkdocs-macros and are defined in the mkdocs configuration file:

extra:
  commands:
    run: musical-notes

Tools

This project basically uses two tools as the basis for all control:

  • Poetry: For environment management and library installation
  • Taskipy: For automation of routine tasks such as running tests, linters, documentation, etc.

So, make sure you have Poetry installed for this contribution:

pipx install poetry

Steps to perform specific tasks

Aqui estão listados comandos que você pode usar para executar tarefas corriqueiras. Como clonar o repositório, como instalar as dependências, executar os testes e etc...

How to clone the repository

git clone https://github.com/dunossauro/notas-musicais.git

How to install dependencies

poetry install

How to Run the CLI

poetry run musical-notes [subcommand]

How to run code verification

task lint

How to run the tests

task test

How to run the Documentation

task docs