Contributing#

4 minute read.

Contributions are very welcome and appreciated!

You can contribute in many ways.

Please take a moment to read our code of conduct.

Types of Contributions#

Report Bugs#

Report a bug!

A Bug Issue Template is available to assist you provide all the necessary information.

Fix Bugs#

Look through Django Cookiecutter GitHub issues for bugs.

Anything labelled with ‘bug’ and ‘help wanted’ is open to anyone wishing to assist.

Implement Features#

Look through Django Cookiecutter GitHub issues for features.

Anything labelled with ‘enhancement’ and ‘help wanted’ is open to anyone wishing to assist.

Write Documentation#

Django Cookiecutter strives to have excellent documentation for several reasons:

  1. Excellent documentation improves the user’s experience.

  2. Excellent documentation helps when reviewing old features or code.

At the core of that effort is following the Diátaxis Framework and documentation philosophy.

Django Cookiecutter provides the four pillars Tutorials, How-to, Reference and Discussion with templates to make writing documentation easy.

Take a look at our growing list of templates here.

Here is a TLDR of the documentations structure:

  1. Tutorial:

    1. Allow the learner to understand what goals they will achieve before they start.

    2. A tutorial helps a beginner achieve basic competence.

    3. Allow the user to learn by doing.

    4. Get the learner productive and succeeding from the very start.

  2. How-to:

    1. How-to guides are goal-oriented directions, much like a recipe.

    2. The goal of a how-to is to solve a problem or complete an unfamiliar task.

    3. Explanations aren’t necessary when following a how-to guide.

    4. How-to guides should be flexible and adaptable to many use cases.

  3. Reference:

    1. References are technical descriptions of the machinery and how to operate it.

    2. A reference guides focus is the product and must describe it as succinctly as possible.

    3. Users consult reference material, so it should not contain any ambiguity.

  4. Discussions:

    1. Discussions clarify and illuminate a particular topic.

    2. Discussions are understanding-oriented.

    3. Discussions deepen and broaden the reader’s understanding of a subject.

    4. Connections, even to things outside the immediate topic, can add clarity and context.

See this Diátaxis summary for more information to help you write better documentation.

Docstrings#

Django Cookiecutter uses Sphinx to document the API. Class’s, modules, or functions must have at least a single line docstring, ending in a period to pass code quality checks.

The docstring should convey what is done, not how it is done to your users for clarity and consistency.

See the amazing_new_feature.py example below.

 1"""Classes for adding Amazing New Features."""
 2
 3class AmazingNewFeaturesFromOld:
 4    """A class of making old features new again."""
 5
 6    def amazing_new_feature_from_old_1(self):
 7        """Take some old feature and make it fresh again."""
 8
 9    def amazing_new_feature_from_old_2(self):
10        """Take another old feature and make it fresher."""
11
12class AmazingNewFeatures:
13    """A class of making brand new features."""
14
15    def amazing_new_feature_1(self):
16        """Improve user experience feature one."""
17
18    def amazing_new_feature_2(self):
19        """Improve user experience feature two."""

Submit Feedback#

The best way to provide feedback is to file an Issue.

A selection of templates is available to help you get your message across.

  • This is a volunteer-driven project, and all contributions are welcome :)

Get Started#

Ready to contribute?

Here’s how to set up django-cookiecutter for local development. We have demonstrated this is going into a local projects folder.

  1. Create a virtual environment.

Note

The commands to create a virtual environment below will use Python version 3.11. The minumum version for django-cookiecutter is Python 3.10 because Structural Pattern Matching is used.

If you prefer another python version installed on your computer, you can replace python3 with python3.n, where n is the version number.

Important

If you are writing documentation and using a preview function in your IDE then the minimum version for your virtual environment is Python3.9.

The document dependencies are installed by default now when you create your virtual environment.

Select the tab for your preferred Operating System.

bash/zsh#
python3.11 -m venv venv
source venv/bin/acivate
pip install --upgrade pip

You will have a folder structure similar to this.

projects
└── venv
bash/zsh#
python3.11 -m venv venv
source venv/bin/acivate
pip install --upgrade pip

You will have a folder structure similar to this.

projects
└── venv

If you have installed Python in your PATH and PATHEXT.

cmd/PowerShell#
python3.11 -m venv venv

C:\> venv\Scripts\activate.bat  # cmd.exe
PS C:\> venv\Scripts\Activate.ps1 # Powershell

pip install --upgrade pip

Otherwise use

cmd/PowerShell#
c:\>c:\Python311\python -m venv c:\path\to\packages\my_env
PS C:\> <venv>\Scripts\Activate.ps1

C:\> venv\Scripts\activate.bat  # cmd.exe
PS C:\> venv\Scripts\Activate.ps1 # Powershell

pip install --upgrade pip

You will have a folder structure similar to this.

projects
└── venv

  1. From your GitHub account, fork the django-cookiecutter repository.

  2. In your projects folder, clone your fork locally, install the developer requirements and set the local git commit message template.

git clone git@github.com:your_git_user_name_here/django-cookiecutter.git

cd django-cookiecutter

git config --local commit.template .github/.git-commit-template.txt

pip install -r requirements_dev.txt

You will have a folder structure similar to this.

projects
 ├── venv
 └── django-cookiecutter

  1. Create a branch for local development.

git checkout -b issue-nn  # Convention is to use issue number.

git checkout -b name-of-your-bugfix-or-feature # Altenative to the convention.

Now you can make your changes locally.

  1. When you’re changes with tests and documentation are complete, run pre-commit and tox.

git add .
pre-commit
tox

  1. After successful pre-commit and tox, commit your changes and push your branch to GitHub.

Note

Django Cookiecutter uses python-semantic-release.

For semantic version to work, commit messages must follow Conventional Commits.

See an example of how they look here.

If you have followed the contributing guidelines to this point, the local commit message template has help built-in.

git commit
git push origin name-of-your-bugfix-or-feature

  1. Submit a pull request through the GitHub website.

Pull Request Guidelines#

Before you submit a pull request, please check that it meets these guidelines:

  1. The pull request changes must be covered with tests.

  2. If the pull request adds functionality, you should add the functionality to the documentation.

    Documentation templates are provided to assist you.

  3. Your changes must include a docstring to pass code quality checks.

  4. Please run pre-commit and Tox locally before making a pull request.

If you have gotten this far, thank you for your time and contribution.