Skip to content

How to contribute to the project

There are two possible ways to exploit this repo. The first one is to fork, i.e. copy, this repo and use it as a template or starting point to generate your workflow. On the other hand, if you want to improve it, you can copy, modify it and then open a Pull Request to the original repo.

Open issues

If you find bugs or have feature requests, please open an issue. We provide templates to guide the process.

Contribute to the code (a.k.a. open a Pull Request)

Info

This guide assumes that you are able to clone repositories from your GitHub account. One way to do this is by means of ssh keys, however other ways are possible.

To contribute code improvements or new features, follow these steps:

  1. Fork this repository to your GitHub account.
  2. Clone your fork locally: 
    git clone https://github.com/your-username/WP3-P3-md-workflow.git
  3. Create a new branch for your work: 
    git switch -c feat-branch-name
  4. Make your changes and commit them with clear messages: 
    git add -A
git commit -m "Describe your commit"
  5. Push your branch to your fork: 
    git push --set-upstream origin feat-branch-name
  6. Open a Pull Request (PR) to the main repo’s default branch.
  7. Wait for a review before merge.

Python style

Python codes use the ruff formatter in its default configuration. Install ruff (once) and format before committing:

ruff format md/workflow/md.py

IDE integration: Most editors (VS Code, PyCharm, Neovim) support ruff natively through extensions.

Contribute to the documentation

Documentation is built with MkDocs using the Material theme and hosted on GitHub Pages. Documentation is built to be displayed both on GitHub and in an HTML form, hence graphical artifacts might be present.

Preview locally

If using uv: 

uvx --with mkdocs-material mkdocs serve

otherwise

python -m venv .venv
. .venv/bin/activate
python -m pip install -r docs/requirements.txt

Then, open http://127.0.0.1:8000.

Edit workflow

  1. Edit .md files in docs/
  2. Preview changes as described above
  3. Commit and push — docs deploy automatically

Style

  • Use Material alerts
  • Use GitHub Flavored Markdown (tables, code blocks)
  • Keep filenames lowercase with underscores
  • One # heading per file (becomes page title)