Developing
==========

Creating a New Django app
-------------------------

To create a new Django app, you can run

.. code::

    make create-app name=YOUR-APP-NAME-HERE

Be sure to add your newly created app to the ``INSTALLED_APPS`` list within
``/memcollection/settings/base.py``.

Linting
-------

I have set up `Flake8 <https://flake8.pycqa.org/en/latest/>`_ as the linter for this project. You
can run the following command to lint the Python code:

.. code::

    make lint

This command will output any errors into the terminal, but it will NOT automatically fix issues
found. You can either fix them manually, or you can run the formatting command (listed below in the
next section). I have noticed that long lines of strings (like code comments) often have to be fixed
manually.

Formatting
----------

For formatting, I chose to use `Black <https://black.readthedocs.io/en/stable/>`_. You can format
the Python code by running

.. code::

    make format

This command WILL automatically format files, and it'll output in the terminal how many files are
formatted or left unchanged.

Testing
-------

My aim is to have comprehensive test coverage for the various Django apps within the project. I'm
using `unittest <https://docs.python.org/3/library/unittest.html>`_ for, well, the unit tests, as
it's built into the Python Standard Library (I've heard pytest is better, but I'm too lazy to try to
figure out how to configure it in this project). Maybe someday, I'll write a few integration tests
for the different models, but I feel that unit tests provide sufficient test coverage for this
project.

You can execute the tests by running

.. code::

    make test

I set the verbosity to be a little higher (2, vs the default of 1), as I like seeing more details
outputted in the terminal. This setting can be changed by altering the ``test`` command in the
Makefile.

I've also installed `Coverage <https://coverage.readthedocs.io/en/7.6.4/>`_ in this project. You can
see the overall test coverage by running

.. code::

    make coverage

Documenting
-----------

I've set up Sphinx to generate docs from both the ``docs/`` directory, as well as auto-generate docs
from the docstrings present in my apps' various ``models.py`` files (I could have included
docstrings from other types of files, like viewsets and serializers, but the docstrings in those
files are all very similiar to each other, so I didn't see the point). You can generate the docs
locally by running

.. code::

    make build-docs

This will create a ``build/`` folder under ``docs/``. Opening ``build/html/index.html`` in your
browser of choice will allow you to navigate through the docs as though they are hosted on a server
or S3 bucket.

Changelog
---------

I've set up an npm package, `auto-changelog <https://github.com/CookPete/auto-changelog>`_, to
auto-generate a changelog based on my git history. The changelog can be generated by running

.. code::

    make build-changelog

This will output a file, ``changelog.md``, under ``docs/source/``. Sphinx is configured to
incorporate this file within the generated docs.

.. note:: auto-changelog doesn't include PRs I create, so I need to manually add my PRs to the
   outputted file. I add ``<!-- auto-changelog-above -->`` to the top of the changelog so that
   ``make build-changelog`` doesn't overwrite my changes.

``git-flow``
------------

I am using git-flow to manage changes in this project.

Feature Branches
****************

You can create a new feature branch off of ``develop`` by running

.. code::

    git flow feature start NAME-OF-YOUR-FEATURE-BRANCH-HERE

After commiting your changes, you can publish the feature branch on GitHub by
running

.. code::

    git flow feature publish NAME-OF-YOUR-FEATURE-BRANCH-HERE

Open a PR on GitHub; this will lint, format, and test the code before it is merged back into
``develop``. If the tests pass, you can merge your feature branch by running

.. code::

    git flow feature finish NAME-OF-YOUR-FEATURE-BRANCH-HERE

Make sure to push your changes after merging.

Release Branches
****************

To start a release, simply run

.. code::

    git flow release start x.y.z

Make sure to update the version number in ``docs/source/conf.py``,
``memcollection/settings/base.py``, and ``package.json`` and commit those changes:

.. code::

    git add .
    git commit -m "Bump version in docs/source/conf.py, memcollection/settings/base.py, and package.json"

Next, update the changelog by running

.. code::

    make build-changelog

Make any necessary changes/adjustments to the auto-generated output, then commit those changes:

.. code::

    git add .
    git commit -m "Update changelog"

Then, publish the release branch by running

.. code::

    git flow release publish x.y.z

Open a PR on GitHub to merge the release into ``main``. Again, the code will be linted, formatted,
and tested.

If all tests pass, go ahead and run

.. code::

    git flow release finish x.y.z

Follow the prompts in the terminal when merging the release back into both the ``develop`` and ``main``
branches. For the commit message for the tag, just use the version number (x.y.z) as the message.

Make sure to push your changes after merging:

.. code::

    git push origin develop main --no-verify --tags