3. Developers Guide¶

3.1. Contributing Guide¶

Contributions are welcome and greatly appreciated!

3.1.1. Workflow¶

A bug-fix or enhancement is delivered using a pull request. A good pull request should cover one bug-fix or enhancement feature. This strategy ensures the change set is easier to review and less likely to need major re-work or even be rejected.

The workflow that developers typically use to fix a bug or add enhancements is as follows.

Fork the django-odm2 repo into your account.

Obtain the source by cloning it onto your development machine.

$ git clone git@github.com:your_name_here/django-odm2.git
$ cd django-odm2

Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
Familiarize yourself with the developer convenience rules in the Makefile.
```
$ make help
```
Create and activate a Python virtual environment for local development. This rule also specifies a project specific prompt label to use once the virtual environment is activated.
```
$ make venv
$ source venv/bin/activate
(django-odm2) $
```
The ‘venv’ directory is is created under the project root directory and is also listed in the ‘.gitignore’ file so that its contents never accidentally get added to a git change set.

Note

(django-odm2) is used to indicate when the commands should be run within the virtual environment containing the development dependencies.
Develop fix or enhancement:
- Make a fix or enhancement (e.g. modify a class, method, function, module, etc).
- The change should be style compliant. Perform style check.
```
(django-dm2) $ make check-style
```
  Run ‘make style’ to automatically apply style fixes if needed. See the Code Style section for more information.
- The change should pass static analysis checks (linting and type annotations where appropriate). Perform static analysis check.
```
(django-odm2) $ make check-static-analysis
```
  See the Static Analysis section for more information.
- Fix any errors or regressions.
The docs and the change log should be updated for anything but trivial bug fixes. Perform docs check.
(django-odm2) $ make docs
See the Documentation section for more information.
Commit and push changes to your fork.
```
$ git add .
$ git commit -m "A detailed description of the changes."
$ git push origin name-of-your-bugfix-or-feature
```
A pull request should preferably only have one commit upon the current master HEAD, (via rebases and squash).
Submit a pull request through the service website (e.g. Github, Gitlab).
Check automated continuous integration steps all pass. Fix any problems if necessary and update the pull request.

3.2. Code Style¶

Adopting a consistent code style assists with maintenance. This project uses Blue to format code and isort to sort imports. Use the Makefile convenience rule to apply code style fixes.

(django-odm2) $ make style

3.2.1. Code Formatting¶

A Makefile convenience rule exists to perform just code format fixes.

(django-odm2) $ make format

3.2.2. Import Sorting¶

A Makefile convenience rule exists to perform just module import sorting fixes.

(django-odm2) $ make sort-imports

3.3. Static Analysis¶

A Makefile convenience rule exists to simplify performing static analysis checks. This will perform linting and type annotations checks.

(django-odm2) $ make check-static-analysis

3.3.1. Code Linting¶

A Makefile convenience rule exists to perform code linting checks.

(django-odm2) $ make check-lint

3.3.2. Type Annotations¶

The code base contains type annotations to provide helpful type information that can improve code maintenance. A Makefile convenience rule exists to check no type annotations issues are reported.

(django-odm2) $ make check-types

3.4. Documentation¶

To rebuild this project’s documentation, developers should use the Makefile in the top level directory. It performs a number of steps to create a new set of sphinx html content.

(django-odm2) $ make docs

To quickly check consistency of ReStructuredText files use the dummy run which does not actually generate HTML content.

(django-odm2) $ make check-docs

To quickly view the HTML rendered docs, start a simple web server and open a browser to http://127.0.0.1:8000/.

(django-odm2) $ make serve-docs

3.5. Release Process¶

The following steps are used to make a new software release.

The steps assume they are executed from within a development virtual environment.

Check that the package version label in __init__.py is correct.

Create and push a repo tag to Github. As a convention use the package version number (e.g. YY.MM.MICRO) as the tag.

$ git checkout master
$ git tag YY.MM.MICRO -m "A meaningful release tag comment"
$ git tag  # check release tag is in list
$ git push --tags origin master

This will trigger Github to create a release at:

https://github.com/{username}/django-odm2/releases/{tag}

Create the release distribution. This project produces an artefact called a pure Python wheel. The wheel file will be created in the dist directory.
```
(django-odm2) $ make dist
```
Upload the release to PyPI using
```
(django-odm2) $ make dist-upload
```
The package should now be available at https://pypi.org/project/django-odm2/