Skip to content

Latest commit

 

History

History
163 lines (115 loc) · 4.9 KB

contributing.md

File metadata and controls

163 lines (115 loc) · 4.9 KB

Contributing

Thank you for taking an interest in contributing to Gourmand! We appreciate that you're thinking about offering your time to improving the project, and it's our goal to respect your contribution accordingly.

Although this document focuses on code contributions, you can contribute in several ways:

  • File a bug report.
  • Add or improve documentation.
  • Promote the project to others.

Contributing Code

In general, the process for contributing code is:

  1. Pick or open an issue to work on
  2. Post a comment expressing your intent to make sure nobody else is already working on it
  3. Set up a development environment, as described below
  4. Do your changes, and when ready
  5. Push your changes to your forked repo and create a pull request.

Setting Up a Development Environment

Fork and clone Gourmand.

Ensure your system has the necessary prerequisites installed:

  • Python, which is what Gourmand is written in.
  • PyGObject for GTK+ 3 and other GNOME libraries. You may either install your system's pygobject package(s) or install the necessary system requirements to install pygobject from PyPI with pip. The latter method is recommended if you plan on doing development within a Python virtual environment.
  • intltool for internationalization.
  • (optional) Enchant for spell-checking. At least one of the backends must be installed as well.
  • (optional) GStreamer for sound. The GStreamer library itself and gst-plugins-base are required. Python bindings are provided through PyGObject, so GObject introspection data is also needed.
  • (optional) poppler for exporting PDFs. Python bindings are provided through PyGObject, so install the GLIB bindings and associated GObject introspection data.

Note: Although some prerequisites are optional, the development install of Gourmand enables all plugins and features, so you probably want to install all prerequisites to avoid any issues.

You may want to set up a Python virtual environment. This is optional but highly recommended:

$ python -m venv --prompt gourmand venv
$ source venv/bin/activate
(gourmand) $ pip install -U pip setuptools wheel

Then install Gourmand itself:

(gourmand) $ pip install -r development.in

This installs the remaining Python dependencies and Gourmand itself in editable mode, which allows you to run Gourmand and see your changes without having to reinstall it.

Note: If you encounter an error during the installation of pygtkspellcheck, first install pyenchant and pygobject on their own:

(gourmand) $ pip install pyenchant pygobject
(gourmand) $ pip install -r development.in

You should now be able to launch and run Gourmand:

(gourmand) $ gourmand

Style

Gourmand uses ruff for checking the code style, while trying to closely follow PEP 8.

Check the style:

ruff check src/ tests/ setup.py

Issues and Suggestions

We welcome feedback and issue reporting. You can do so by browsing existing issues and commenting on them, or creating a new one.

When reporting an issue, please fill in the provided template.

For feedback or requests of features, please explain with details, and screenshots if possible, what you would like.

Translations

The following describes how to contribute translation.

Update the translation template:

cd po/
intltool-update -p -g gourmand

A file gourmand.pot should have been modified. Add it to git.

If modifying an already existing translation, update the translation file:

msgmerge --update --no-fuzzy-matching --backup=off fr.po gourmand.pot

If adding translation for a new language, copy the file for your target language, such as fr.po or de_AT.po, if translating for a specific region, and add it to git.

Once the translation is done, update the translations:

python setup.py build_i18n

Launch Gourmand and check the changes.
Once satisfied, open a pull request with your work.

Testing

Gourmand have a test suite in the tests directory. Patches that expands it are welcome. It is run with pytest:

LC_ALL=C pytest

Most modern python IDEs have support for running the tests usin pytest.

Warning: Running the tests will most likely mess with your local configuration and database file. Please make sure to backup the corresponding directory content manually BEFORE running the tests.

Blaming

Consider using

git blame --ignore-revs-file .git-blame-ignore-revs

instead of plain blaming to ignore some mostly irrelevant commits.