Skip to content

Development

Local installation¤

Start by forking the project by clicking the Fork button up in the right corner in the GitHub. This makes a copy of the repository in your own name. Now you can clone this repository locally and start adding features:

git clone https://github.com/<your GitHub username>/django-components.git
cd django-components

To quickly run the tests install the local dependencies by running:

pip install -r requirements-dev.txt

You also have to install this local django-components version. Use -e for editable mode so you don't have to re-install after every change:

pip install -e .

Running tests¤

Now you can run the tests to make sure everything works as expected:

pytest

The library is also tested across many versions of Python and Django. To run tests that way:

pyenv install -s 3.8
pyenv install -s 3.9
pyenv install -s 3.10
pyenv install -s 3.11
pyenv install -s 3.12
pyenv install -s 3.13
pyenv local 3.8 3.9 3.10 3.11 3.12 3.13
tox -p

To run tests for a specific Python version, use:

tox -e py38

NOTE: See the available environments in tox.ini.

Linting and formatting¤

To check linting rules, run:

ruff check .
# Or to fix errors automatically:
ruff check --fix .

To format the code, run:

ruff format --check .
# Or to fix errors automatically:
ruff format .

To validate with Mypy, run:

mypy .

You can run these through tox as well:

tox -e mypy,ruff

Playwright tests¤

We use Playwright for end-to-end tests. You will need to install Playwright to run these tests.

Luckily, Playwright makes it very easy:

pip install -r requirements-dev.txt
playwright install chromium --with-deps

After Playwright is ready, run the tests the same way as before:

pytest
# Or for specific Python version
tox -e py38

Dev server¤

How do you check that your changes to django-components project will work in an actual Django project?

Use the sampleproject demo project to validate the changes:

  1. Navigate to sampleproject directory:

    cd sampleproject

  2. Install dependencies from the requirements.txt file:

    pip install -r requirements.txt

  3. Link to your local version of django-components:

    pip install -e ..

    Note

    The path to the local version (in this case ..) must point to the directory that has the pyproject.toml file.

  4. Start Django server:

    python manage.py runserver

Once the server is up, it should be available at http://127.0.0.1:8000.

To display individual components, add them to the urls.py, like in the case of http://127.0.0.1:8000/greeting

Building JS code¤

django_components uses a bit of JS code to:

  • Manage the loading of JS and CSS files used by the components
  • Allow to pass data from Python to JS

When you make changes to this JS code, you also need to compile it:

  1. Navigate to src/django_components_js:

    cd src/django_components_js

  2. Install the JS dependencies

    npm install

  3. Compile the JS/TS code:

    python build.py

    The script will combine all JS/TS code into a single .js file, minify it, and copy it to django_components/static/django_components/django_components.min.js.

Documentation website¤

The documentation website is built using MkDocs and Material for MkDocs.

First install dependencies needed for the documentation:

pip install -r requirements-docs.txt

Then install this local django-components version. Use -e for editable mode so you don't have to re-install after every change:

pip install -e .

To run the documentation server locally, run:

mkdocs serve

Then open http://127.0.0.1:9000/django-components/ in your browser.

To just build the documentation, run:

mkdocs build

The documentation site is deployed automatically with Github actions (see .github/workflows/docs.yml).

The CI workflow runs when:

  • A new commit is pushed to the master branch - This updates the dev version
  • A new tag is pushed - This updates the latest version and the version specified in the tag name

Publishing¤

We use Github actions to automatically publish new versions of django-components to PyPI when a new tag is pushed. See the full workflow here.

Commands¤

We do not manually release new versions of django-components. Commands below are shown for reference only.

To package django-components into a distribution that can be published to PyPI, run build:

# Install pypa/build
python -m pip install build --user
# Build a binary wheel and a source tarball
python -m build --sdist --wheel --outdir dist/ .

To then publish the contents of dist/ to PyPI, use twine (See Python user guide):

twine upload --repository pypi dist/* -u __token__ -p <PyPI_TOKEN>

Release new version¤

Let's say we want to release a new version 0.141.6. We need to:

  1. Bump the version in pyproject.toml to the desired version.

    [project]
version = "0.141.6"

  2. Create a summary of the changes in CHANGELOG.md at the top of the file.

    When writing release notes for individual changes, it's useful to write them like mini announcements:

    • Explain the context
    • Then the change itself
    • Then include an example
    # Release notes

## v0.141.6

_2025-09-24_

#### Fix

- Tests - Fix bug when using `@djc_test` decorator and the `COMPONENTS`
  settings are set with `ComponentsSettings`
  See [#1369](https://github.com/django-components/django-components/issues/1369)

    Note

    When you include the release date in the format _YYYY-MM-DD_, it will be displayed in the release notes.

    See docs/scripts/gen_release_notes.py for more details.

    Example of a changelog entry

  3. Create a new PR to merge the changes above into the master branch.

  4. Create new release in Github UI.

    Github UI release part 1 Github UI release part 2 Github UI release part 3 Github UI release part 4

Semantic versioning¤

We use Semantic Versioning for django-components.

The version number is in the format MAJOR.MINOR.PATCH (e.g. 0.141.6).

  • MAJOR (e.g. 1.0.0) is reserved for significant architectural changes and breaking changes.
  • MINOR (e.g. 0.1.0) is incremented for new features.
  • PATCH (e.g. 0.0.1) is incremented for bug fixes or documentation changes.

Development guides¤

Head over to Dev guides for a deep dive into how django_components' features are implemented.

Maintenance¤

Updating supported versions¤

The scripts/supported_versions.py script can be used to update the supported versions.

python scripts/supported_versions.py

This will check the current versions of Django and Python, and will print to the terminal all the places that need updating and what to set them to.

The scripts/validate_links.py script can be used to update the link references.

python scripts/validate_links.py

When new version of Django is released, you can use the script to update the URLs pointing to the Django documentation.

First, you need to update the URL_REWRITE_MAP in the script to point to the new version of Django.

Then, you can run the script to update the URLs in the codebase.

python scripts/validate_links.py --rewrite

Project management¤

Project board¤

We use the GitHub project board to manage the project.

Quick overview of the columns:

  • No status - Issues that are not planned yet and need more discussion
  • 🔵 Backlog - Planned but not ready to be picked up
  • 🟢 Ready - Ready to be picked up
  • 🟡 In Progress - Someone is already working on it
  • 🟣 Ready for release - Completed, but not released yet
  • 🟠 Done - Completed and released

New issues are automatically added to the No status column.

To pick up an issue, assign it to yourself and move it to the 🟡 In Progress column.

Project board

Use the sidebar to filter the issues by different labels, milestones, and issue types:

Project board filter

Priority¤

Which issues should be picked up first?

We suggest the following guideline:

  1. Bugs - First fix bugs and documentation errors.
  2. V1 release - Then pick up issues that are part of the v1 release milestone.

After that, pick what you like!

Labels¤

Labels help keep our project organized. See the list of all labels here.

Milestones¤

Issue types¤