mirror of
https://github.com/spiral-project/ihatemoney.git
synced 2025-05-06 13:01:50 +02:00
Reorganize "Contributing" documentation to be more accessible to new contributors
The following changes were done: - move "How to contribute" first, and "Set up a dev environment" as the second section. This way, a new contributor has access to the most general information first, instead of the very specific "dev environment" documentation. - reduce "How to contribute" / "As a developer" by moving the part about tests to a new "Contributing as a developer" section (see below). This way, all types of contributions get roughly the same amount of text in the first "How to contribute" section. - add a new "Contributing as a developer" section, which lists items that are useful when preparing a code contribution (running tests, formatting code, create database migration). These items were moved either from "How to contribute" or from "Set up a dev environment".
This commit is contained in:
Baptiste Jonglez
parent
10c35e41ce
commit
5492c9dcbc
1 changed files with 100 additions and 76 deletions
|
|
@ -1,6 +1,56 @@
|
||||||
Contributing
|
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
|
Set up a dev environment
|
||||||
========================
|
========================
|
||||||
|
|
||||||
|
|
@ -45,8 +95,56 @@ In case you want to update to newer versions (from Git), you can just run the "u
|
||||||
|
|
||||||
make update
|
make update
|
||||||
|
|
||||||
Create database migrations
|
Useful settings
|
||||||
--------------------------
|
----------------
|
||||||
|
|
||||||
|
It is better to actually turn the debugging mode on when you're developing.
|
||||||
|
You can create a ``settings.cfg`` file, with the following content::
|
||||||
|
|
||||||
|
DEBUG = True
|
||||||
|
SQLACHEMY_ECHO = DEBUG
|
||||||
|
|
||||||
|
You can also set the `TESTING` flag to `True` so no mails are sent
|
||||||
|
(and no exception is raised) while you're on development mode.
|
||||||
|
Then before running the application, declare its path with ::
|
||||||
|
|
||||||
|
export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg"
|
||||||
|
|
||||||
|
.. _contributing-developer:
|
||||||
|
|
||||||
|
Contributing as a developer
|
||||||
|
===========================
|
||||||
|
|
||||||
|
All code contributions should be submitted as Pull Requests on the
|
||||||
|
`github project <https://github.com/spiral-project/ihatemoney>`_.
|
||||||
|
|
||||||
|
Below are some points that you should check to help you prepare your Pull Request.
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
make test
|
||||||
|
|
||||||
|
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.
|
||||||
|
To do so, just run::
|
||||||
|
|
||||||
|
make black isort
|
||||||
|
|
||||||
|
You can also integrate them with your dev environment (as a *format-on-save*
|
||||||
|
hook, for instance).
|
||||||
|
|
||||||
|
Creating database migrations
|
||||||
|
----------------------------
|
||||||
|
|
||||||
In case you need to modify the database schema, first make sure that you have
|
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
|
an up-to-date database by running the dev server at least once (the quick way
|
||||||
|
|
@ -78,80 +176,6 @@ which can be created with the following command::
|
||||||
|
|
||||||
You then need to write the migration steps yourself.
|
You then need to write the migration steps yourself.
|
||||||
|
|
||||||
Useful settings
|
|
||||||
----------------
|
|
||||||
|
|
||||||
It is better to actually turn the debugging mode on when you're developing.
|
|
||||||
You can create a ``settings.cfg`` file, with the following content::
|
|
||||||
|
|
||||||
DEBUG = True
|
|
||||||
SQLACHEMY_ECHO = DEBUG
|
|
||||||
|
|
||||||
You can also set the `TESTING` flag to `True` so no mails are sent
|
|
||||||
(and no exception is raised) while you're on development mode.
|
|
||||||
Then before running the application, declare its path with ::
|
|
||||||
|
|
||||||
export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg"
|
|
||||||
|
|
||||||
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. 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::
|
|
||||||
|
|
||||||
make test
|
|
||||||
|
|
||||||
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.
|
|
||||||
To do so, just run::
|
|
||||||
|
|
||||||
make black isort
|
|
||||||
|
|
||||||
You can also integrate them with your dev environment (as a *format-on-save*
|
|
||||||
hook, for instance).
|
|
||||||
|
|
||||||
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!
|
|
||||||
|
|
||||||
How to build the documentation ?
|
How to build the documentation ?
|
||||||
================================
|
================================
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue