Implement Wagtail Python Package Maintenance Guidelines

[Stormheg]

see https://github.com/wagtail/wagtail/wiki/Python-Package-Maintenance-Guidelines

Since wagtail-bakery is a first-party package we should aim to implement these guidelines.

I've copied the guidelines here and added tick marks for what needs to be done.

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
  • License
  • PyPI
• Should have a badge linking to online code coverage results
  • Note: badge is there, link is broken Removed the badge for now
• Must link to the changelog
• Must mention what versions of Python, Django and Wagtail are supported
  • Note: refers to 'current LTS, current stable' which can be quite outdated. Could be improved by including a table of supported versions.
• 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)
  • Note: refers to examples in subdirectories of the repository. Could be improved.
• Must link to the Github discussions board that should be enabled on the repo (see Support)
• Must mention where to report security issues ([email protected])

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
  • 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 We use py.test, which is acceptable
• 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
  • Note: black is missing

Support

• Should provide support through Github Discussions

[loicteixeira]

I've updated the first message after merging your last PR.
I also created the missing tags, releases and stable branches on GitHub.

However, I don't have the permissions to:

1. rename the master branch to main
2. enable GitHub discussions

Any owner on the Wagtail organization should be able to do it. Maybe @allcaps or @kaedroho? 🙏

[allcaps]

@Stormheg @loicteixeira master is renamed to main.

[allcaps]

The default branch has been renamed!
master is now named main

If you have a local clone, you can update it by running the following commands.

git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

[loicteixeira]

Awesome thank you 🙏

[loicteixeira]

First comment updated with:

• eaa5dcb added PyPI badges, removed coverage one (it was broken), added security policy, added link to discussions.
• ticked At least two core team members must have admin access now that the project is within the wagtail-nest org
• remove outdated notes (e.g. no changelog) even though we had ticked the box.