Skip to content

Commit

Permalink
Improve import data and contributing section
Browse files Browse the repository at this point in the history
  • Loading branch information
@bruhnild
bruhnild committed Jan 8, 2025
1 parent 2c4a5fb commit c7646de
Show file tree
Hide file tree
Showing 13 changed files with 646 additions and 641 deletions.
131 changes: 16 additions & 115 deletions docs/contribute/contributing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,124 +2,25 @@
Contributing
============

Conventions
-----------
As Geotrek-admin is an open-source software application supported by its community, all contributions are welcome. You can help us in many ways, without necessarily requiring technical skills.

* Before contributing, open an issue and discuss about it with community (is it a bug or a feature ? What is the best way to achieve my goal ?)
* Use flake8
* KISS & DRY as much as possible
* Elegant and generic is good, simple is better
* Separate bug fixes and new features in several pull requests.
* Open a new Pull Request in "Draft" status until tests passed. Use at least 'bug', 'improvement' or 'feature' label.
* Commits messages are explicit and mention issue number (``(ref #12)`` or ``(fixes #23)``), they should contains corresponding tag (see below)
* Features are developed in a branch and merged from Github pull-requests.
Ways to contribute
--------------------

Definition of done
------------------
For non technical profiles
~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``docs/changelog.rst`` is up-to-date
* An explicit unit-test covers the bugfix or the new feature.
* A frontend test (:path:jstests/nav-\*.js) covers the navigation bug fix or feature
* A JS *Mocha* test (:path:jstests/tests.\*.js) covers the JavaScript bug fix or feature
* Unit-tests total coverage is above or at least equal with previous commits. Patch coverage is 100% on new lines.
* Settings have default value in ``settings/base.py``
* Installation instructions and documentation are up-to-date

Check TODO in the source tree:

::

find geotrek | xargs egrep -n -i '(TODO|XXX|temporary|FIXME)'


Pull requests
-------------

Before creating a pull request, ensure you follow thoses rules :

* Follow the guidelines of this page
* Self-review your code
* Add comments in your code, particularly in hard-to-understand areas
* Make corresponding changes to the documentation
* There is tests that prove my fix is effective or that my feature works.
* All new lines of code are tested
* There is an entry in the changelog file (with the corresponding issue referenced)

It is important to add a label to the pull request corresponding to the perimeter. Release notes are generated according to labels of pull requests. This is the list of available labels for pull requests:

+-----------------+---------------+-----------------------+---------+
| Tag | Branch prefix | Emoji code | Unicode |
+=================+===============+=======================+=========+
| Improvements | impr\_ | dizzy | 💫 |
+-----------------+---------------+-----------------------+---------+
| Bug fixes | bug\_ | bug | 🐛 |
+-----------------+---------------+-----------------------+---------+
| Features | feat\_ | sparkles | ✨ |
+-----------------+---------------+-----------------------+---------+
| Documentation | doc\_ | memo | 📝 |
+-----------------+---------------+-----------------------+---------+
| Maintenance | maint\_ | building_construction | 🏗 |
+-----------------+---------------+-----------------------+---------+
| Refactor | ref\_ | recycle | ♻ |
+-----------------+---------------+-----------------------+---------+
| Dependencies | dep\_ | arrow_up | ⬆ |
+-----------------+---------------+-----------------------+---------+
| CI/CD | cicd\_ | construction_worker | 👷 |
+-----------------+---------------+-----------------------+---------+
| Performances | perf\_ | zap | ⚡ |
+-----------------+---------------+-----------------------+---------+
| UI/UX | uiux\_ | lipstick | 💄 |
+-----------------+---------------+-----------------------+---------+
| Security | sec\_ | lock | 🔒 |
+-----------------+---------------+-----------------------+---------+
| Translations | trans\_ | globe_with_meridians | 🌐 |
+-----------------+---------------+-----------------------+---------+
| Hotfix | hot\_ | ambulance | 🚑 |
+-----------------+---------------+-----------------------+---------+
| Breaking change | break\_ | boom | 💥 |
+-----------------+---------------+-----------------------+---------+

Commits in pull requests are following a naming convention in order to easily establish their perimeter. Commit is formated as ``emoji [tag] description of commit``.

You can use one of the above prefix for your commits but also one of the following (tags used only for commits, not for pull requests):

========= ========================= ========
Tag Emoji code Unicode
========= ========================= ========
Codestyle art 🎨
Clean fire 🔥
Tests white_check_mark ✅
Release bookmark 🔖
Merge twisted_rightwards_arrows 🔀
========= ========================= ========


Release
--------

On master branch:

* Update files *VERSION* and *docs/changelog.rst* to remove ``+dev`` suffix and increment version (please use semver rules)
* Run ``dch -r -D RELEASED``, update version in the same way and save
* Commit with message 'Release X.Y.Z' and push to ``master``
* Create new release with name 'Geotrek-admin X.Y.Z' on Github, with tag X.Y.Z, click on "Generate release notes"
* Wait for release to be published through CI
* Update files *VERSION* and *docs/changelog.rst* to add ``+dev`` suffix
* Run ``dch -v <version>+dev --no-force-save-on-release`` and save
* Commit with message 'Back to development' and push to ```master``

* When creating a new release 'X.Y.Z' on github, Github actions will generate the .deb package file, and publish it on https://packages.geotrek.fr (see ``.github/workflows/test.yml`` file for details)
* Help the users and answers questions on the `mailing-list <https://groups.google.com/g/geotrek-fr>`_ ;
* Take part in `working group <https://geotrek.ecrins-parcnational.fr/ressources/gt/>`_ or `online discussions <https://github.com/GeotrekCE/Geotrek-admin/discussions>`_ on Geotrek development to share your vision and needs.
* `Open a ticket <https://github.com/GeotrekCE/Geotrek-admin/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=>`_ when you encounter a bug ;
* `Open a ticket <https://github.com/GeotrekCE/Geotrek-admin/issues/new?assignees=&labels=&projects=&template=feature_request.md&title=>`_ when you have a suggestion or feature idea ;
* To help spread Geotrek internationaly you can translate in other languages (:ref:`see dedicated section <translating-geotrek>`) :
* Translate the documentation ;
* Translate the user interface (menus, buttons, labels, etc.).

Other ways to contribute
-------------------------
For web enthousiasts
~~~~~~~~~~~~~~~~~~~~~~

* Help the users and answers questions on the `mailing-list <https://groups.google.com/g/geotrek-fr>`_ ;
* `Open a ticket <https://github.com/GeotrekCE/Geotrek-admin/issues/new>`_ when you encounter a bug ;
* `Open a ticket <https://github.com/GeotrekCE/Geotrek-admin/issues/new>`_ when you have a suggestion or feature idea ;
* Translate the documentation ;
* Translate the menus, buttons and labels (we use `Weblate <https://weblate.makina-corpus.net>`_) ;
* Maintain the installation script for different Linux distributions (*requires some basic Linux skills*) ;
* Fix bugs or improve layout and apparence (*requires Webmaster skills*) ;
* Fix bugs or improve core modules (*requires python/Django skills*).
* Propose UI/UX improvements by creating `an issue in Github <https://github.com/GeotrekCE/Geotrek-admin/issues/new?assignees=&labels=&projects=&template=feature_request.md&title=>`_.
* Develop bug fixes or improvements. We recommand to follow guideline (see section bellow and :ref:`Developement section <development-section>`.) and starting with `easing picking tagged issues <https://github.com/GeotrekCE/Geotrek-admin/issues?q=is%3Aissue+is%3Aopen+label%3Aeasy-picking>`_.

Join the `mailing list <https://groups.google.com/forum/#!forum/geotrek-fr>`_! Send an email to ``[email protected]`` and you will receive an invitation automatically.
117 changes: 56 additions & 61 deletions docs/contribute/development.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ Go to ``http://geotrek.local:8000`` in your browser

PDF generation might not work unless you use this domain and is correctly set to ``SERVER_NAME`` variable in your ``.env`` file.


Install git hooks
=================

Expand All @@ -36,25 +35,28 @@ Install git hooks
ln -s -f ../../.githooks/pre-push .git/hooks/pre-push
ln -s -f ../../.githooks/pre-commit .git/hooks/pre-commit


Adding or upgrade dependencies
==============================

Consider using pip-tools to manage dependencies.

* add your dependencies in ``setup.py`` for general dependencies, ``dev-requirements.in`` for dev dependencies, then run:

::

make deps
.. md-tab-set::
:name: upgrade-dependencies-tabs

or
.. md-tab-item:: With Make

::
.. code-block:: python
make deps
docker compose run --rm web pip-compile
docker compose run --rm web pip-compile dev-requirements.in
.. md-tab-item:: With Docker

.. code-block:: python
docker compose run --rm web pip-compile
docker compose run --rm web pip-compile dev-requirements.in
Model modification
==================
Expand All @@ -77,9 +79,9 @@ When updating or adding a new field ``my_field`` to a model ``MyModel``, please

- If ``my_field`` is a ``ForeignKey``:

- make sure to override ``related_name`` with an explicit set name
- make sure to override ``related_name`` with an explicit set name

- if ``my_field`` causes cascading deletion (argument ``on_delete=models.CASCADE``), make sure to log potential deletions (see example ``log_cascade_deletion_from_sector_practice`` in ``geotrek/outdoor/models.py``)
- if ``my_field`` causes cascading deletion (argument ``on_delete=models.CASCADE``), make sure to log potential deletions (see example ``log_cascade_deletion_from_sector_practice`` in ``geotrek/outdoor/models.py``)

- Make sure to set ``verbose_name`` on the field and add proper translations in ``.po`` files

Expand All @@ -89,106 +91,106 @@ When updating or adding a new field ``my_field`` to a model ``MyModel``, please

- Look for form class ``MyModelForm(CommonForm)`` :

- If it exists, and field needs to be included in form, add ``my_field`` to form attributes (``fields`` on the ``Meta`` class, sometimes ``fieldslayout`` as well).
- If it exists, and field needs to be included in form, add ``my_field`` to form attributes (``fields`` on the ``Meta`` class, sometimes ``fieldslayout`` as well).

- If field is added to the form **and is optional**, please add ``my_field`` to the documentation for hideable form fields : in ``docs/advanced-configuration.rst`` look for ``HIDDEN_FORM_FIELDS['mymodel']`` and add your field to the list.
- If field is added to the form **and is optional**, please add ``my_field`` to the documentation for hideable form fields : in ``docs/advanced-configuration.rst`` look for ``HIDDEN_FORM_FIELDS['mymodel']`` and add your field to the list.

- Look for list view class ``MyModelList(CustomColumnsMixin, MapEntityList)`` :

- If it exists, please add ``my_field`` to the documentation for custom list view columns : in ``docs/advanced-configuration.rst`` look for ``COLUMNS_LISTS['mymodel_view']`` and add your field to the list.
- If it exists, please add ``my_field`` to the documentation for custom list view columns : in ``docs/advanced-configuration.rst`` look for ``COLUMNS_LISTS['mymodel_view']`` and add your field to the list.

- If it exists, and if you wish to display a column for ``my_field`` in the list view for this model by default, simply add ``my_field`` to ``default_extra_colums`` on this class.
- If it exists, and if you wish to display a column for ``my_field`` in the list view for this model by default, simply add ``my_field`` to ``default_extra_colums`` on this class.

- Look for exports view class ``MyModelFormatList(MapEntityFormat, MyModelList)`` :

- If it exists, please add ``my_field`` to the documentation for custom list exports columns : in ``docs/advanced-configuration.rst`` look for ``COLUMNS_LISTS['mymodel_export']`` and add your field to the list.
- If it exists, please add ``my_field`` to the documentation for custom list exports columns : in ``docs/advanced-configuration.rst`` look for ``COLUMNS_LISTS['mymodel_export']`` and add your field to the list.

- If it exists, and if you wish to display a column for ``my_field`` in CSV/SHP exports for this model by default, simply add ``my_field`` to ``default_extra_colums`` on this class.
- If it exists, and if you wish to display a column for ``my_field`` in CSV/SHP exports for this model by default, simply add ``my_field`` to ``default_extra_colums`` on this class.

- Follow the documentation you just edited to test that custom columns and hideable fields do work properly with your new field.

- Look for sql file defaults ``geotrek/{app_name}/sql/post_90_defaults.sql`` :

- If it exists find your modelname in the list and depending on the default value alter column ``my_field`` or add ``-- my_field``
- If it exists find your modelname in the list and depending on the default value alter column ``my_field`` or add ``-- my_field``

- If the modelname doesn't exist, create a new section (even if you don't need to alter column)
- If the modelname doesn't exist, create a new section (even if you don't need to alter column)

- Look for sql view file ``geotrek/{app_name}/sql/post_20_views.sql`` and update the view for your model with an alias for the new field


**In API v2** :

If ``MyModel`` is served by APIv2, make sure to add a serializer for the new field in ``geotrek/api/v2/serializers.py`` and if you wish to filter on this field, create a new filter and add it to the right ``ViewSet`` under ``geotrek/api/v2/views``, using attribute ``filter_backends``.


When updating a field ``my_field`` in a model ``MyModel`` for ``new_field``, check if this field is translated in ``geotrek/{app}/translation.py``.

If so, you need to add a migration just after the migration generated by Django.
This migration should rename the old fields generated by modeltranslation ``my_field_en`` by ``new_field_en``
(example : ``geotrek/trekking/migrations/0014_auto_20200228_2127.py``)


Check quality
=============

**Flake8**

run:
.. md-tab-set::
:name: flake-tabs

::

make flake8


or
.. md-tab-item:: With Make

::
.. code-block:: python
make flake8
docker compose run --rm web flake8 geotrek
.. md-tab-item:: With Docker

.. code-block:: python
docker compose run --rm web flake8 geotrek
Run tests
=========

**Django tests :**

run:
To run all test suites and report global coverage:

::

make coverage
make coverage

To run a specific test suite:

To run all test suites and report global coverage
.. md-tab-set::
:name: test-specific-tabs

.. md-tab-item:: With Make

To run a specific test suite, run:
.. code-block:: python
make coverage
::
.. md-tab-item:: With Docker

make tests
.. code-block:: python
docker compose run --rm -e ENV=tests web ./manage.py test
or
You can run test with non dynamic segmentation :

::
.. md-tab-set::
:name: test-nds-tabs

docker compose run --rm -e ENV=tests web ./manage.py test
.. md-tab-item:: With Make

.. code-block:: python
make tests_nds
And


::

make tests_nds

or

::

docker compose run --rm -e ENV=tests_nds web ./manage.py test

.. md-tab-item:: With Docker

.. code-block:: python
docker compose run --rm -e ENV=tests_nds web ./manage.py test
**Cypress tests :**

Expand All @@ -199,7 +201,6 @@ Create an empty project with Docker :
docker compose down
docker compose up -d


Install elements for the cypress tests

::
Expand All @@ -208,31 +209,26 @@ Install elements for the cypress tests
make load_test_integration
make load_test_integration_workflow


Move in cypress folder and install

::

cd cypress
npm ci


Launch tests

::

./node_modules/.bin/cypress run


Pictures of the problem and videos are generated in ``cypress/videos`` and ``cypress/screenshots``.


Setup to use screamshotter-related features locally
===================================================

Use the domain defined in ``SERVER_NAME`` in your ``.env`` to reach your local Geotrek-admin web instance. By default the address is ``http://geotrek.local:8000``.


Database reset
==============

Expand Down Expand Up @@ -260,10 +256,9 @@ Mapentity development

See `Django-Mapentity documentation <https://django-mapentity.readthedocs.io/>`_


UML diagrams of data model
==========================

UML diagrams of Geotrek-admin data models are available in ``docs/data-model`` directory.
UML diagrams of Geotrek-admin data models are available in `docs/data-model <https://github.com/GeotrekCE/Geotrek-admin/tree/master/docs/data-model>`_ directory.
To regenerate them from PostgreSQL, install postgresql-autodoc and graphviz Ubuntu packages
and run ``make uml``.
Loading

0 comments on commit c7646de

Please sign in to comment.