=================
Delphi API README
=================

The Delphi Products API (a.k.a. Apps API).

:Release:
    .. image:: https://img.shields.io/badge/release-v3.0-blue.svg?style=flat-square

:Maintained by:
    Delphi Team – Sony Music Data & Analytics


Principles
----------

Design principles are based on:

- `Google's API Design Guide`_
- `API First Design`_
- `OpenAPI v3 Specification`_

  .. _Google's API Design Guide: https://cloud.google.com/apis/design/
  .. _API First Design: https://swagger.io/resources/articles/adopting-an-api-first-approach/
  .. _OpenAPI v3 Specification: https://swagger.io/specification/


Features
--------

- The Connexion_ Framework on top of Flask_
- `Postgres (v11)`_

  .. _Connexion: https://connexion.readthedocs.io/en/latest/index.html
  .. _Flask: http://flask.palletsprojects.com/en/1.1.x/
  .. _Postgres (v11): https://www.postgresql.org/docs/11/


Workflow
--------

This repo's Git workflow follows `Github Flow`_.

  .. _Github Flow: https://guides.github.com/introduction/flow/

1. Create a branch off of ``master``
2. Commit and push your branch code
3. Open a pull request on Github for code review and QA testing


If another pull request has been merged into master before yours, it is _preferable_ to **rebase** your branch,
and force push your changes. However, if multiple developers are working on your branch, merging master
into your branch and makes more sense (to avoid force pushing which could allow for lost updates).


Rebasing Tips
~~~~~~~~~~~~~

Here are two ways to rebase your branch's code (optionally ``-i`` for interactive):

  .. code-block:: bash

    git checkout <yourbranch>
    git fetch origin master
    git rebase -i origin/master

Alternatively, This method checks out master and pulls, but requires extra steps:

  .. code-block:: bash

    git checkout master
    git pull
    git checkout <yourbranch>
    git rebase -i master

With **PyCharm**, the process is the most straightforward:

1. Checkout ``master`` branch and pull the latest
2. Click on your branch from the Git list in the bottom toolbar, and select
   "Checkout and Rebase onto Current"
3. Force push your branch to the remote


Useful make Commands
--------------------
- ``make help`` - list the available make commands and descriptions
- ``make docker-compose/run`` - builds and runs the containers via docker-compose (RECOMMENDED).
- ``make clean`` - clean unnecessary files
- ``make codegen`` - compiles the protocol buffer files (``.proto``) to Python (requires ``protoc``)†
- ``make devenv`` - create local virtual env from ``requirements-dev.txt``
- ``make docker/build`` - build api Docker image from Dockerfile
- ``make docker/login`` - aws configuration needs to be set first
- ``make docker/push`` - push an image to a registry
- ``make docker/run-test`` - build and run the api test Docker image from Dockerfile.test
- ``make docs`` - build the HTML docs using Sphinx_
- ``make frozen-dev`` - update the frozen ``requirements-dev.txt`` file based on the ``requirements/dev.pip`` file
- ``make frozen`` - update the frozen ``requirements.txt`` file based on the ``requirements/base.pip`` file
- ``make lint`` - run ``pylint`` on the codebase
- ``make sort-imports`` - run ``isort`` on the project and test modules
- ``make venv`` - create local virtual env from ``requirements.txt``


†You can install ``protoc`` on MacOS with ``brew install protobuf``

Notes
~~~~~

- When running ``make test`` or ``make lint``, dependencies from ``requirements/test.pip`` will be installed.
- When runing  ``make venv`` ``requirements/base.pip`` dependencies will be installed.


Running the Docker Container
----------------------------

Ensure you have ``docker-compose`` installed. If not, you can install it using homebrew:

  .. code-block:: bash

    brew install docker-compose


Build and run the container:

  .. code-block:: bash

    make docker-compose/run


Running the Test Container
--------------------------
The unit tests are run in a separate container for the test build step in Jenkins. To run this
container locally, you can run the following command:

  .. code-block:: bash

    DOCKER_BUILDKIT=1 make docker/run-test


Getting Set Up Locally
----------------------

1. You'll want to create a virtualenv if you haven't already for Delphi API:

  .. code-block:: bash

    python3 -m venv && source /venv/bin/activate


2. Install the development requirements and Delphi API package:

  .. code-block:: bash

    pip install -r requirements/dev.pip
    python3 install -e .


Generating Documentation
------------------------
This project's documentation from code can be automatically generated via Sphinx_.

The below assumes you have already followed the steps above in "Getting Set Up Locally".

.. _Sphinx: http://www.sphinx-doc.org/en/stable/index.html

1. Generate the stub ``.rst`` files and the HTML browser files with make from the project root:

  .. code-block:: bash

    make docs


Linting Your Code
-----------------
Run before pushing:

  .. code-block:: bash

    make sort-imports


Checking Code Quality
---------------------
Use the pylint command to check quality of code updates:

  .. code-block:: bash

    make lint


Creating Releases
-----------------
Use bump2version_ to create a new Delphi API release.

  .. code-block:: bash

    # dry-run to see what will happen
    bump2version --verbose patch --allow-dirty --dry-run

    # update patch version
    bump2version --verbose patch

.. _bump2version: https://github.com/c4urself/bump2version