django-components/docs/community/development.md

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`](https://github.com/django-components/django-components/blob/master/docs/scripts/gen_release_notes.py) for more details.
   
   ![Example of a changelog entry](../images/release-notes-dates.png){ width="250" }
   

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

4. Create new release in Github UI.

   

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.

Updating link references

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.

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

{ width="250" }

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

• milestone--v1 - Work to be done for the V1 release.

Issue types

• type--bug - Bugs.
• type--documentation - Documentation changes.
• type--enhancement - New features and improvements.
• type--integration - Integrating with other libraries or systems.
• type--operations - Relating to "operations" - Github Actions, processes, etc.
• type--optimisation - Optimizing the code for performance.