Developing

Creating a New Django app

To create a new Django app, you can run

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 as the linter for this project. You can run the following command to lint the Python 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. You can format the Python code by running

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 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

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 in this project. You can see the overall test coverage by running

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

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, to auto-generate a changelog based on my git history. The changelog can be generated by running

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

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

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

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

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

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:

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

make build-changelog

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

git add .
git commit -m "Update changelog"

Then, publish the release branch by running

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

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:

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