diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9a8529c..6df6a910 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,9 @@ The **GitHub** repository contains: - tests, - documentation (source and build). +Continuous integration workflows run on **Github Actions** platform (on **push** and **pull requests**). + + ### How to install FitTrackee see [Installations instructions](https://samr1.github.io/FitTrackee/installation.html) @@ -48,7 +51,7 @@ Please make your changes from the development branch (`dev`). ``` * Check the downgrade migration. -* Run checks (lint, typecheck and tests). +* Run checks (lint, type check and unit tests). ```shell $ make check-all ``` @@ -59,9 +62,9 @@ Please make your changes from the development branch (`dev`). * If needed, add or update tests. -* If needed, update documentation. +* If needed, update documentation (no need to build documentation, it will be done when releasing). -* If code contains client changes, you can generate a build, in a **separate commit** to ease code review. +* If updated code contains client-side changes, you can generate a build, in a **separate commit** to ease code review (or to easily drop it in case of conflicts when updating your branch). ```shell $ make build-client ``` diff --git a/docsrc/source/installation.rst b/docsrc/source/installation.rst index 2a90925a..9df5ed70 100644 --- a/docsrc/source/installation.rst +++ b/docsrc/source/installation.rst @@ -14,17 +14,18 @@ This application is written in Python (API) and Typescript (client): - `Leaflet `__ to display map - `Chart.js `__ to display charts with elevation and speed -Logo, sports and weather icons are made by `Freepik `__ from `www.flaticon.com `__. +| Logo, some sports and weather icons are made by `Freepik `__ from `www.flaticon.com `__. +| FitTrackee also uses icons from `Fork Awesome `__. Prerequisites ~~~~~~~~~~~~~ -- PostgreSQL database (10+) -- Redis for task queue - Python 3.7+ -- `Poetry `__ (for installation from sources only) -- API key from `Dark Sky `__ [not mandatory] +- PostgreSQL database (10+) - SMTP provider +- Redis for task queue (to send emails) +- API key from `Dark Sky `__ [not mandatory] +- `Poetry `__ (for installation from sources only) - `Yarn `__ (for development only) - Docker and Docker Compose (for development or evaluation purposes) @@ -108,7 +109,7 @@ deployment method. | Database URL with username and password, must be initialized in production environment. | For example in dev environment : ``postgresql://fittrackee:fittrackee@localhost:5432/fittrackee`` - .. danger:: + .. warning:: | Since `SQLAlchemy update (1.4+) `__, engine URL should begin with `postgresql://`. @@ -209,12 +210,25 @@ To send emails, a valid ``EMAIL_URL`` must be provided: - with SSL: ``smtp://username:password@smtp.example.com:465/?ssl=True`` - with STARTTLS: ``smtp://username:password@smtp.example.com:587/?tls=True`` +.. warning:: + | If the email URL is invalid, the application may not start. .. versionadded:: 0.5.3 | Credentials can be omitted: ``smtp://smtp.example.com:25``. | If ``:`` is omitted, the port defaults to 25. +.. warning:: + | Since 0.6.0, newly created accounts must be confirmed (an email with confirmation instructions is sent after registration). + +Emails sent by FitTrackee are: + +- account confirmation instructions +- password reset request +- email change (to old and new email adresses) +- password change + + Map tile server ^^^^^^^^^^^^^^^ .. versionadded:: 0.4.0 @@ -423,7 +437,7 @@ Upgrade From PyPI ^^^^^^^^^ -- Activate the virtualenv +- Stop the application and activate the virtualenv - Upgrade with pip @@ -444,7 +458,6 @@ From PyPI $ fittrackee_upgrade_db - - Restart the application and task queue workers. @@ -647,8 +660,7 @@ Installation .. versionadded:: 0.4.4 -For evaluation purposes , docker files are available, -installing **FitTrackee** from **sources**. +For evaluation purposes, docker files are available, installing **FitTrackee** from **sources**. - To install **FitTrackee** with database initialisation and run the application and dramatiq workers: diff --git a/docsrc/source/troubleshooting/administrator.rst b/docsrc/source/troubleshooting/administrator.rst index 103af8a4..698be811 100644 --- a/docsrc/source/troubleshooting/administrator.rst +++ b/docsrc/source/troubleshooting/administrator.rst @@ -5,10 +5,18 @@ Administrator `FitTrackee fails to start` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Check the database URL in `Environment variables <../installation.html#envvar-DATABASE_URL>`__ if the following error is displayed in **gunicorn** logs: +- Check the database URL in `environment variables <../installation.html#envvar-DATABASE_URL>`__ if the following error is displayed in **gunicorn** logs: -.. code:: + .. code:: - sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres + sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres -It must start with `postgresql://` (engine URLs starting with `postgres://` are no longer supported). \ No newline at end of file + It must start with `postgresql://` (engine URLs starting with `postgres://` are no longer supported). + +- Check the email URL in `environment variables <../installation.html#envvar-EMAIL_URL>`__ if the following error is displayed in **gunicorn** logs: + + .. code:: + + fittrackee.emails.exceptions.InvalidEmailUrlScheme + + A valid ``EMAIL_URL`` must be provided (see `emails <../installation.html#emails>`__). \ No newline at end of file diff --git a/docsrc/source/troubleshooting/index.rst b/docsrc/source/troubleshooting/index.rst index 17388a46..ac232b9d 100644 --- a/docsrc/source/troubleshooting/index.rst +++ b/docsrc/source/troubleshooting/index.rst @@ -3,7 +3,6 @@ Troubleshooting .. toctree:: :maxdepth: 2 - :caption: Endpoints: administrator user