Skip to content

Latest commit

 

History

History
326 lines (228 loc) · 13 KB

RELEASE.md

File metadata and controls

326 lines (228 loc) · 13 KB
Raw

Release

Table of Contents

Pinax Starter Project and App Release

Pinax Starter Projects

The contents of each individual starter project branch of the Pinax starter projects repo becomes a tagged release available on the Pinax starter projects repo releases page.

Pinax Apps

The contents of each Pinax app repo becomes a tagged release available on the repo releases page and published to the Python Package Index (PyPi), where developers store packages for reuse by themselves and other developers.

You can search PyPI for all of the Pinax published packages!

High Level Release Process

Apps Typically Involved

  • Apps included in last release
  • pinax-starter-app
  • pinax-cli
  • pinax-templates
  • Any apps that can be brought up to date

Must Have Improvements

  • Drop support for Python and Django versions that are no longer officially supported
  • Add support for Python and Django versions that are officially supported

Nice to Have Improvements

  • Automation improvements
  • Increased DRY-ness.
  • Continuous Integration (CI) improvements
  • Packaging improvements

How to Know What Changes to Make

Dropping and Adding Support for Python and Django Versions

Generally, Pinax supports the officially supported versions of Python and Django.

For more information, see the following Django docs:

Additional Sources of Info

The Latest GitHub Features

Release Management

Oversight

  • Update wiki with current and historical release info (See: https://github.com/pinax/pinax/wiki)
  • Use a spreadsheet to track updates to individual apps
  • Use GitHub milestones within repos, as needed

Release Versioning

  • Pinax releases follow the CalVer (Calendar Versioning) specification.
  • Use yy.mm for a limited timeframe, where yy is the year and mm is the month.
  • Use yy.xx for an unlimited timeframe, where yy is the year

App Versioning

Tagging

In each repo "tags" section click on "Releases" and "Draft a new release"

  • Target branch should be set to master
  • For "Tag version" use v1.2.3 format
  • For "Release title" use 1.2.3 format
  • Use the README.md Change Log entry for release notes, either by copy and paste or markdown hyperlink

Publishing to PyPI

Some of this guidance was taken from the PyPI packaging tutorial.

setuptools, wheel, and twine should be installed

Updated Method

Force removal of untracked files and directories

$ git clean -fdx

Generate distribution packages for the package

$ python3 setup.py sdist bdist_wheel
Upload to PyPI Test Instance

Upload to PyPI test instance... go to the test instance page to double check that everything looks right

$ python3 -m twine upload --repository testpypi dist/*

Install new package from test instance

$ python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps
Upload to PyPI

Upload to PyPI

$ python3 -m twine upload dist/*

Install new package from PyPI

$ pip install <package>

Previous Method

This method (pre-Python 3) did not use twine, which is now considered a best practice.

Force removal of untracked files and directories

$ git clean -fdx

Publish to PyPI

$ python setup.py sdist bdist_wheel upload

Release Planning Checklist

  • Supported versions matrix updated with supported Python and Django versions
  • Dependencies up-to-date, accurate, and documented (setup.py and README.md)
  • setup.py consistent across all apps
  • Consistent use of SemVer and Change Log
  • Ensure that community health files in the global community health file are up-to-date

Testing and Release Checklist

  • Make the relevant updates to the app repo, based on the guidance in release plan
  • Make the relevant GitHub Actions and tox updates based on the guidance on the release plan
  • Run the Makefile using the Make command to test the new supported versions matrix
  • Fix the errors you see in the terminal until you see green at the end of the process
  • Update Change Log
  • Update app version number in setup.py (Pinax uses SemVer)
  • Create a pull request

Release Pull Request Checklist

Before publishing

  • Accurate pull request; unit test(s) included, if needed
  • Updated app version number in setup.py (Pinax apps use SemVer)
  • Updated Change Log, using new app version number

Publishing

  • Ensure AUTHORS file is up-to-date (it's possible the process will be automated)
  • Tag the release
  • Package should be automatically published to PyPI or test instance of PyPI by new PyPI GitHub Action anytime a tagged commit is pushed

After publishing

  • App PyPI page renders properly (Note: if you need to re-publish, PyPI will not let you use the existing version number; consider publishing to the test instance of PyPI first)

Documentation, Tutorials, Demos

Must Have

  • Accurate installation instructions (Apps included in the most recent release should all have basic installation instructions)

Nice to Have

  • Improved usage docs
  • New tutorials
  • New or improved Pinax Starter Project
  • New or improved demo that showcases a Pinax Starter Project or app

Community

  • Ensure repo has a correct, up-to-date LICENSE, if needed (Most Pinax repos include an MIT License; some dates could be incorrect at this time, especially for deprecated or non-app repos)
  • Mark deprecated repos as deprecated, especially in the repo description line
  • Add repo tags (Possible tags: django-project-template, python, django, pinax)

Development Files

Several of the files outside of the Pinax project and app folders are configuration files used in the development process.

Pinax Starter Project Development Files

Folder/File Description
.gitignore Tells git which files to exclude when work is pushed to GitHub
Pipfile
setup.cfg
update.sh A shell script used to automate commands

Pinax App Development Files

Folder/File Description
.circleci/config.yml
.coveragerc
.gitignore Tells git which files to exclude when work is pushed to GitHub
MANIFEST.in
Makefile
makemigrations.py
runtests.py
setup.py
tox.ini A tox config file

Development Tools Overview

Supported Versions Matrix Testing

tox is used to test the supported versions matrix. detox, a tox plugin used to run tox testenvs in parallel, has been used in Pinax extensively in the past, but will be replaced with tox parallel mode. detox is now an archived project.

Run Supported Versions Matrix Tests

All apps should include a Makefile.

Run the Makefile:

    $ Make

Continuous Integration

Code Coverage

Codecov is used to provide coverage reports. Coverage is required to collect coverage metrics.

Style, Linting, and Import Sorting

Flake8 is used to check style and complexity. Flake8 includes Doc8 style checker, pydocstyle docstring style checker, and McCabe complexity checker.

Flake8 Quotes, a Flake8 extension for quote linting, is used to enforce double quotes. This is a Pinax design choice.

isort is used to programmatically sort imports.

Spread the Word

Release blog post

  • Release stats
  • Credit to contributors, including new features