Rooba
/
wagtail
mirror of https://github.com/wagtail/wagtail.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Page: Python Package Maintenance Guidelines
Pages
Accessibility team Accessible image model working group Contributed apps and website code Contributors calendar Core team participation Creating a new TWIW email shot Creating a new Wagtail release Developer relations team Documentation search Edit ephemeral Squash sites Google Season of Docs 2023 Google Summer of Code 2021 Google Summer of Code 2022 Google Summer of Code 2023 Google Summer of Code Home Managing Wagtail translations Nightly testing of official plugins Outreachy 2022 PR triage Packaging Team Performance team Project finances Python Package Maintenance Guidelines Release schedule Roadmap Search backend implementation notes Security team Slack Stock responses for GitHub Issues StreamField blocks API Sustainability team The Zen of Wagtail UI team Updating PRs for linting changes Wagtail Hosting Providers Wagtail core team Wagtail sub teams
6 Python Package Maintenance Guidelines
Thibaud Colas edited this page 2022-11-04 09:15:40 +00:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

These guidelines should be followed by maintainers of Python packages that are hosted on Wagtail’s GitHub organisation.

These guidelines exist to improve consistency between packages that are maintained by the Wagtail core team. This makes it easier for contributors to submit patches and core team members to perform administrative tasks on any packages in the Wagtail organisation.

Notes on language:

  • All guidelines are worded to contain either the word Should or Must.
  • Where Must is used in a guideline, this means that not following the guideline will be considered a bug.
  • Where Should is used in a guideline, this means that the package maintainer is encouraged to follow it to improve consistency with other packages, but not following it would not be considered a bug.

Adding new guidelines

  • To suggest a new guideline, open a Github discussion or add it to the core team meeting agenda
  • Guidelines should not be idealistic. Please do not suggest anything that isn’t already in use on multiple packages
  • If there is any disagreement about whether a guideline should exist or its wording, it should be left out. We can always add it later

Documentation

Readme

  • Must be written in Markdown and named README.md
  • Must be visible on PyPI and renders properly
  • Must have badges linking to PyPI and license
  • Should have a badge linking to online code coverage results
  • Must link to the changelog
  • Must mention what versions of Python, Django and Wagtail are supported
  • Must include an installation guide. This could be an abridged version of what is in the docs, but it must link to the full guide in the docs if this is the case
  • Must link to full documentation (or, for small packages, documentation included directly in the readme)
  • Must link to the Github discussions board that should be enabled on the repo (see Support)
  • Must mention where to report security issues (security@wagtail.io)

Documentation

Note: Small packages may use their readme as documentation. These guidelines only apply when documentation separate to the readme exists.

  • Must be available on the web
  • Must be written in markdown
  • Must be linked to from readme
  • Must mention what versions of Python, Django and Wagtail are supported
  • Must have an installation guide and a usage guide
  • Should have reference or explanation, depending on the complexity of the package

Changelog

  • Must have a changelog named CHANGELOG.md
  • Should follow Keep a Changelog

Contributing guide

  • Must have a contributing guide which is named CONTRIBUTING.md

License

  • Must have a permissive licence (such as BSD or MIT, but not GPL)
  • Should be licensed under BSD 3-clause, if possible
  • Must have a license file at the top of the repo

setup.py / setup.cfg / pyproject.toml

  • Dependency versions should be as wide as possible
  • Support for EOL versions of Python, Django and Wagtail should be removed from the earliest minor release of the package following the moment the dependency went EOL. This does not apply if provision is made to maintain support for the EOL dependency.
  • Testing and documentation requirements listed in extras
  • Must have classifiers for Python, Django and Wagtail versions
  • Must have classifier for license
  • Must have project URLs linking to Documentation and Changelog

Development Process

Branching

  • Default branch must be called main
  • Each major release must have a branch prefixed with “stable”. For example stable/1.0.x. This is to allow security fixes to be backported

Releases

  • Version numbers must follow PEP440
  • Each release must have a git tag and a github release
  • Each release must be mentioned in the changelog
  • Each release must be published to PyPI

PyPI

  • Package must have a PyPI page
  • At least two core team members must have admin access
    • Note: Everyone who has permission to publish an official Wagtail package must have 2FA enabled on their PyPI account. Remember to check this when adding collaborators (this is visible in the PyPI web UI)

Automated testing

Django unit tests

  • Should use Django’s built-in test framework
  • Must have unit test coverage of at least 85%
  • Should aim for unit test coverage of at least 90%
  • Migrations and tests must be excluded from coverage reports
  • Must have instructions on how to run unit tests

Continuous Integration

  • Must have a Continuous Integration set up with Github Actions, Circle CI, or both
  • Should test against Wagtail nightly and report issues to #nightly-build-failures channel
  • Must be linted with flake8
  • Should be formatted with black and isort

Support

  • Should provide support through Github Discussions

New packages

EOL (End of Life) packages

  • The repository must be archived and moved to the wagtail-deprecated organisation
  • A message must be added to the readme. This should be visible on both PyPI as well

Github tips

  • To remove the 'packages' section from a Github project's about sidebar, click the small cog next to the word 'about', then untick packages.

Home

Teams

How To