Developer Guidelines
====================

* GitLab Project: https://gitlab.com/ppc-robot/ppc-robot
* YouTrack: https://hub.lynt.cz/hub/projects/PPC_Robot
* Issues: https://youtrack.lynt.cz/issues/R


Recommended Tools
-----------------

* PyCharm: https://www.jetbrains.com/pycharm/
* PyCharm YouTrack plugin: https://plugins.jetbrains.com/plugin/8215-youtrack-integration
  (`How-To: Set-Up the YouTrack plugin <https://docs.google.com/document/d/1X9aQYkWMQ2rRdwzZYyzJt3rfDXFA206fJUklGN4iaYA/edit#heading=h.q2b5bqiqq0m2>`_ )
* PyCharm editorconfig: https://plugins.jetbrains.com/plugin/7294-editorconfig


Coding Standard
---------------

Formatting is defined in the ``.editorconfig`` file.


Python
^^^^^^

`Coding standard PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ is used for development. It is the default standard
in PyCharm and other IDEs.


Development Workflow
--------------------

We use Feature Branching. Each branch is named according to the following schema::

    R-<NUM>-<short-description>

Replace ``<NUM>`` by issue number in YouTrack, and ``<short-description>`` by short human-readable title of the issue.
The short description should help in navigation between branches, so it should be as concise as possible.
Use lowercase letters and dashes to separate words. If you are working on feature that has no assigned issue number,
use ``XX`` instead.

Examples of good branch names::

    R-101-sklik-images-report
    R-105-sklik-banners-fix
    R-230-payment-card
    R-231-text-ads-mirroring
    R-XX-sklik-api-update

Not very good branch names::

    R-230-payment_card (uses underscore instead of dashes)
    R-101-SKLIK-IMAGES-REPORT (uppercase letters)
    R-payment-card (missing issue number)
    R-230-enable-users-to-pay-with-credit-and-debit-cards (description too long)

When your changes are ready to review, create a Merge Request.


Commit Messages
^^^^^^^^^^^^^^^

Highly-recommended reading for writing good commit messages: https://chris.beams.io/posts/git-commit/

The first line of the commit message should contain YouTrack issue identifier at the end of the line. Example::

    Fix fetching image URLs from Sklik banner report #R-105

This identifier is used to link commits with issues in YouTrack. You can navigate to commit in GitLab from YouTrack
and vice-versa. This identifier is allowed to exceed the limit of 72 chars for summary line, as it is intended mainly
for machines and it usually takes precious 7 chars.

You can use the commit commands to manipulate with the issues in YouTrack:
https://www.jetbrains.com/help/youtrack/standalone/Apply-Commands-in-VCS-Commits.html

Example::

    Fix fetching image URLs from Sklik banner report #R-105 To Verify

This commit changes the issue state to To Verify. These commands are executed when they are pushed.