Contributing — I hate money 5.0 documentation (2024)

As a developer¶

If you want to contribute code, you can write it and then issue a pullrequest on github. To get started, please read Set up a dev environment andContributing as a developer.

As a designer / Front-end developer¶

Feel free to provide mockups, or to involve yourself in the discussionshappening on the GitHub issue tracker. All ideas are welcome. Of course,if you know how to implement them, feel free to fork and make a pullrequest.

As a translator¶

If you’re able to translate Ihatemoney in your own language, head overto the website we use fortranslationsand start translating.

All the heavy lifting will be done automatically, and your strings willeventually be integrated.

Once a language is ready to be integrated, add it to theSUPPORTED_LANGUAGES list, in ihatemoney/default_settings.py.

End-user¶

You are using the application and found a bug? You have some ideas abouthow to improve the project? Please tell us by filling a newissue.

Thanks again!

The quick way¶

If System installation-requirements arefulfilled, you can just issue:

make serve

It will setup a Virtualenvironment, installdependencies, and run the test server.

The hard way¶

Alternatively, you can use pip to install dependencies yourself. Thatwould be:

pip install -e .

And then run the application:

cd ihatemoneypython run.py

The docker way¶

If you prefer to use docker, then you can build your image with:

docker build -t ihatemoney .

Accessing dev server¶

In any case, you can point your browser at http://localhost:5000.It’s as simple as that!

Updating¶

In case you want to update to newer versions (from Git), you can justrun the “update” command:

make update

Useful settings¶

It is better to actually turn the debugging mode on when you’redeveloping. You can create a settings.cfg file, with the followingcontent:

DEBUG = TrueSQLACHEMY_ECHO = DEBUG

Then before running the application, declare its path with :

export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg"

You can also set the TESTING flag to True so no mails are sent (andno exception is raised) while you’re on development mode.

In some cases, you may need to disable secure cookies by settingSESSION_COOKIE_SECURE to False. This is needed if you access yourdev server over the network: with the default value ofSESSION_COOKIE_SECURE, the browser will refuse to send the sessioncookie over insecure HTTP, so many features of Ihatemoney won’t work(project login, language change, etc).

Running tests¶

Please, think about updating and running the tests before asking for apull request as it will help us to maintain the code clean and running.

To run the tests:

make test

Tests can be edited in ihatemoney/tests/tests.py. If some test casesfail because of your changes, first check whether your code correctlyhandle these cases. If you are confident that your code is correct andthat the test cases simply need to be updated to match your changes,update the test cases and send them as part of your pull request.

If you are introducing a new feature, you need to either add tests toexisting classes, or add a new class (if your new feature issignificantly different from existing code).

Formatting code¶

We are using black andisort formatters for all thePython files in this project. Be sure to run it locally on your files.To do so, just run:

make black isort

You can also integrate them with your dev environment (as aformat-on-save hook, for instance).

Creating database migrations¶

In case you need to modify the database schema, first make sure that youhave an up-to-date database by running the dev server at least once (thequick way or the hard way, see above). The dev server applies allexisting migrations when starting up.

You can now update the models in ihatemoney/models.py. Then run thefollowing command to create a new database revision file:

make create-database-revision

If your changes are simple enough, the generated script will bepopulated with the necessary migrations steps. You can view and edit thegenerated script, which is useful to review that the expected modelchanges have been properly detected. Usually the auto-detection workswell in most cases, but you can of course edit the script to fix smallissues. You could also edit the script to add data migrations.

When you are done with your changes, don’t forget to add the migrationscript to your final git commit!

If the migration script looks completely wrong, remove the script andstart again with an empty database. The simplest way is to remove orrename the dev database located at /tmp/ihatemoney.db, and run the devserver at least once.

For complex migrations, it is recommended to start from an emptyrevision file which can be created with the following command:

make create-empty-database-revision

You then need to write the migration steps yourself.

Requirements¶

To create a new release, make sure you fullfil all requirements:

• Are you a maintainer of the pypi package?

• Are you sure you have no local tags? They will all be published tothe github process as part of the release process

• Make sure you have a ~/.pypirc file with the following content,replacing YOUR_PYPI_USERNAME with your real username:

  [distutils]index-servers = pypi[pypi]username:YOUR_PYPI_USERNAME

Choosing a version number¶

The project follows semantic versioning. To sumthings up:

• if there is a breaking change since the last release: increasethe major version number (11.X.Y → 12.0.0). Example of breakingchanges: drop support for an old version of python, new settingwithout default value (requires an admin to configure the newsetting), changed URL paths, any other incompatible change. Makesure to document the upgrade process.

• if there is a significant new feature or a new setting: increasethe minor version number (11.4.Y → 11.5.0). Make sure todocument any new settings.

• if it’s mostly bugfixes and small changes: increase the patchversion number (11.4.8 → 11.4.9)

Making the release¶

In order to issue a new release, follow the following steps:

• Merge remaining pull requests;

• Switch to the master branch;

• Update CHANGELOG.md with the last changes;

• Update CONTRIBUTORS (instructions inside the file);

• If needed, recompress assets. It requires zopflipng and ImageMagickmogrify:

  make compress-assets

• Extract the translations:

  make extract-translations

• If you’re not completely sure of yourself at this point, you canoptionally: create a new branch, push it, open a pull request, checkthe CI result, and then merge the branch to master.

Once this is done, make sure your local git repository is on the masterbranch, and let’s release!:

make release

This will publish the new version to the Python PackageIndex (PyPI) and publish a tag in the git repository.

Finally, create a release on Github and copy the relevant changelogextract into it.