(packages_guide)=

Packages

Wagtail benefits from a rich ecosystem of packages. Many Python and Django packages work with Wagtail out of the box, and there is a growing collection of Wagtail-specific packages for extending the CMS.

Finding existing packages

The official Wagtail third-party packages directory lists packages organized by category. Forms, migrations, media, integrations, SEO, and more. Awesome Wagtail offers a curated list of packages, articles, and resources.

Many general-purpose Django or Python packages also work directly, or can be integrated directly inside the CMS. Check out the Django Packages directory, or search directly on the Python Package Index (PyPI). You can use the classifier Framework :: Wagtail to find packages that explicitly target Wagtail compatibility.

See How to pick a good Wagtail package for more guidance on how to find and select packages.

Creating packages

We recommend the cookiecutter-wagtail-package template to scaffold a new package with a suitable structure, quality assurance tooling, and other important aspects of package authoring. We also provide guidelines for maintainers, to complement the official Python Packaging User Guide.

To tag your package as compatible with Wagtail, use our official classifier: Framework :: Wagtail. You can also add version-specific classifiers for all major versions, for example: Framework :: Wagtail :: 6.

Package maintenance guidelines

We recommend these guidelines for all packages in our ecosystem. They are particularly important for packages that are part of the first-party Wagtail packages and the Wagtail Nest organization for community-maintained packages.

To meet those guidelines, start your package with our official template: cookiecutter-wagtail-package.

Fundamentals

• Consider naming your package with a wagtail- or django- prefix for ease of identification.
• Use an OSI approved license, shared in a LICENSE file and with publication metadata. We recommend the 3-Clause BSD License.

Documentation

This is crucial to the success of your package.

• We recommend writing all documentation in vanilla Markdown (CommonMark), with minimal to no use of platform-specific extensions.
• Start with a README with basic information about all aspects of the package. Include:
  • Support targets for Python, Django, Wagtail.
  • Simple installation guide.
  • Links to all relevant resources about using or working on the package (documentation, support, security, changelog, etc.).
  • A screenshot of the package user interface, if applicable.
• Create separate files for all aspects of the package to be documented. We recommend the Diátaxis documentation structure.
  • Produce reference documentation for all public APIs of the package.
  • Create how-to material for common usage scenarios.
  • Add a beginner tutorial for first-time users of the package.
  • Add a user guide if the package includes a user interface.
  • Create a CONTRIBUTING.md guide for contributors.
• Consider publishing the package documentation as a website.

Demos

• Include a demo project in the package repository to help contributors and potential new users.
• Demonstrate functionality with freely-licensed content where possible.

Package metadata

Use the pyproject.toml format and standardized fields for as many aspects of the package as possible.

• Dependency versions should be as wide as possible.
• Use optional dependency groups for development dependencies.
• Use classifiers for supported Python, Django, and Wagtail versions.
• Use supported project URLs to link to resources about the package.

Support targets

We recommend broad support targets matching those of Wagtail.

• Follow Wagtail’s Compatible Django / Python versions. See the current supported versions of Python, supported versions of Django, current supported versions of Wagtail.
• Avoid supporting End-Of-Life (EOL) versions of Python / Django / Wagtail. Where feasible, support should be removed from the earliest minor release of the package following the moment the dependency went EOL.
• Use requires-python to declare the lowest version of Python supported by the package, and dependencies for the minimum-supported versions of Django and Wagtail.
• Avoid declaring the highest supported versions of Python or dependencies with a version upper bound.
• Support all database backends supported by Wagtail.
• Strive to match Wagtail’s Browser and device support and Accessibility targets.
• Aim for fully translated and localized interfaces, including right-to-left language support. See Multilingual support.
• Follow the same accessibility standards as Wagtail. See Wagtail’s accessibility statement. Accessibility can be difficult to implement or test - reach out to Wagtail’s accessibility team to validate your approach or test the package.

Quality assurance

• Set up linting and auto-formatting for Python code, Django templates, and other code where possible.
• Use @wagtail/stylelint-config-wagtail for CSS linting, and @wagtail/eslint-config-wagtail for JS linting.
• Write unit tests using Django’s built-in test framework.
• Aim for unit test coverage above 90% (excluding migrations).
• Set up continuous integration to automatically test every change to the package. Continuous integration should include:
  • Matrix testing across a representative range of supported Python / Django / Wagtail versions.
  • Security scanning of project code and dependencies.
  • Recommended: nightly testing of official plugins.
• Set up automation to manage the project’s dependencies.

Releases

• Follow Semantic Versioning and PEP 440 – Version Identification and Dependency Specification.
• Document changes in a CHANGELOG.md following the Keep a Changelog format.
• Document upgrade considerations when releasing breaking changes to the package.
• Use a git va.b.c git tag and repository releases.
• Release to PyPI with a Trusted Publisher set up in Continuous Integration.
• Use a stable/a.b.x branch when working on patch releases to previous versions.

Collaborative maintenance

• Follow the Wagtail Code of Conduct.
• For End of Life (EOL) packages, add a message to the package README, and visible on PyPI as well. For official packages, we additionally transfer them to the wagtail-deprecated organization on GitHub.
• Share PyPI access to the package with at least one or two other people to reduce the bus factor on maintainers.
• If your package is part of an organization, add it to the corresponding PyPI org (see Wagtail on PyPI and Wagtail Nest on PyPI).