diff options
Diffstat (limited to 'docs/contributing.rst')
| -rw-r--r-- | docs/contributing.rst | 165 |
1 files changed, 99 insertions, 66 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 27f890b..3401524 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,6 +1,56 @@ Contributing ############ +.. _how-to-contribute: + +How to contribute +================= + +You would like to contribute? First, thanks a bunch! This project is a small +project with just a few people behind it, so any help is appreciated! + +There are different ways to help us, regarding if you are a designer, +a developer or an user. + +As a developer +-------------- + +If you want to contribute code, you can write it and then issue a pull request +on github. To get started, please read :ref:`setup-dev-environment` and +:ref:`contributing-developer`. + +As a designer / Front-end developer +----------------------------------- + +Feel free to provide mockups, or to involve yourself in the discussions +happening 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 pull request. + +As a translator +--------------- + +If you're able to translate Ihatemoney in your own language, +head over to `the website we use for translations <https://hosted.weblate.org/projects/i-hate-money/i-hate-money/>`_ +and start translating. + +All the heavy lifting will be done automatically, and your strings will +eventually be integrated. + +Once a language is ready to be integrated, add it to the +``SUPPORTED_LANGUAGES`` list, in ``ihatemoney/default_settings.py``. + +End-user +-------- + +You are using the application and found a bug? You have some ideas about how to +improve the project? Please tell us `by filling a new issue <https://github.com/spiral-project/ihatemoney/issues>`_. +Or, if you prefer, you can send me an e-mail to `alexis@notmyidea.org` and I +will update the issue tracker with your feedback. + +Thanks again! + +.. _setup-dev-environment: + Set up a dev environment ======================== @@ -45,39 +95,6 @@ In case you want to update to newer versions (from Git), you can just run the "u make update -Create database migrations --------------------------- - -In case you need to modify the database schema, first make sure that you have -an up-to-date database by running the dev server at least once (the quick way -or the hard way, see above). The dev server applies all existing migrations -when starting up. - -You can now update the models in ``ihatemoney/models.py``. Then run the following -command to create a new database revision file:: - - make create-database-revision - -If your changes are simple enough, the generated script will be populated with -the necessary migrations steps. You can view and edit the generated script, which -is useful to review that the expected model changes have been properly detected. -Usually the auto-detection works well in most cases, but you can of course edit the -script to fix small issues. You could also edit the script to add data migrations. - -When you are done with your changes, don't forget to add the migration script to -your final git commit! - -If the migration script looks completely wrong, remove the script and start again -with an empty database. The simplest way is to remove or rename the dev database -located at ``/tmp/ihatemoney.db``, and run the dev server at least once. - -For complex migrations, it is recommended to start from an empty revision file -which can be created with the following command:: - - make create-empty-database-revision - -You then need to write the migration steps yourself. - Useful settings ---------------- @@ -93,26 +110,38 @@ Then before running the application, declare its path with :: export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg" -How to contribute -================= +.. _contributing-developer: -You would like to contribute? First, thanks a bunch! This project is a small -project with just a few people behind it, so any help is appreciated! +Contributing as a developer +=========================== -There are different ways to help us, regarding if you are a designer, -a developer or an user. +All code contributions should be submitted as Pull Requests on the +`github project <https://github.com/spiral-project/ihatemoney>`_. -As a developer --------------- +Below are some points that you should check to help you prepare your Pull Request. -If you want to contribute code, you can write it and then issue a pull request -on github. Please, think about updating and running the tests before asking for -a pull request as it will help us to maintain the code clean and running. +Running tests +------------- + +Please, think about updating and running the tests before asking for a pull request +as it will help us to maintain the code clean and running. -To do so:: +To run the tests:: make test +Tests can be edited in ``ihatemoney/tests/tests.py``. If some test cases fail because +of your changes, first check whether your code correctly handle these cases. +If you are confident that your code is correct and that 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 to existing classes, +or add a new class (if your new feature is significantly different from existing code). + +Formatting code +--------------- + We are using `black <https://black.readthedocs.io/en/stable/>`_ and `isort <https://timothycrosley.github.io/isort/>`_ formatters for all the Python files in this project. Be sure to run it locally on your files. @@ -123,35 +152,39 @@ To do so, just run:: You can also integrate them with your dev environment (as a *format-on-save* hook, for instance). -As a designer / Front-end developer ------------------------------------ +Creating database migrations +---------------------------- -Feel free to provide mockups, or to involve yourself in the discussions -happening 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 pull request. +In case you need to modify the database schema, first make sure that you have +an up-to-date database by running the dev server at least once (the quick way +or the hard way, see above). The dev server applies all existing migrations +when starting up. -As a translator ---------------- +You can now update the models in ``ihatemoney/models.py``. Then run the following +command to create a new database revision file:: -If you're able to translate Ihatemoney in your own language, -head over to `the website we use for translations <https://hosted.weblate.org/projects/i-hate-money/i-hate-money/>`_ -and start translating. + make create-database-revision -All the heavy lifting will be done automatically, and your strings will -eventually be integrated. +If your changes are simple enough, the generated script will be populated with +the necessary migrations steps. You can view and edit the generated script, which +is useful to review that the expected model changes have been properly detected. +Usually the auto-detection works well in most cases, but you can of course edit the +script to fix small issues. You could also edit the script to add data migrations. -Once a language is ready to be integrated, add it to the -``SUPPORTED_LANGUAGES`` list, in ``ihatemoney/default_settings.py``. +When you are done with your changes, don't forget to add the migration script to +your final git commit! -End-user --------- +If the migration script looks completely wrong, remove the script and start again +with an empty database. The simplest way is to remove or rename the dev database +located at ``/tmp/ihatemoney.db``, and run the dev server at least once. -You are using the application and found a bug? You have some ideas about how to -improve the project? Please tell us `by filling a new issue <https://github.com/spiral-project/ihatemoney/issues>`_. -Or, if you prefer, you can send me an e-mail to `alexis@notmyidea.org` and I -will update the issue tracker with your feedback. +For complex migrations, it is recommended to start from an empty revision file +which can be created with the following command:: + + make create-empty-database-revision + +You then need to write the migration steps yourself. -Thanks again! How to build the documentation ? ================================ |