Ability to ship alpha and beta releases

[simonw]

I'd like to be able to ship alphas and betas to PyPI so in-development plugins can depend on them and help test unreleased plugin hooks.

[simonw]

These should not be shipped as the latest version on Docker Hub. They also should not become the "stable" release on ReadTheDocs.

[simonw]

I'd like this soon, because I want to start experimenting with things like #852 and #842 without shipping those plugin hooks in a full stable release.

[simonw]

Relevant PEP: https://www.python.org/dev/peps/pep-0440/

Django's implementation dates back 8 years: django/django@40f0ecc

From the PEP:

Implicit pre-release number

Pre releases allow omitting the numeral in which case it is implicitly assumed to be 0. The normal form for this is to include the 0 explicitly. This allows versions such as 1.2a which is normalized to 1.2a0.

I'm going to habitually include the 0.

[simonw]

I thought I might have to update a regex (my CircleCI configs won't match on a0, example) but it turns out Travis is currently configured to treat ALL tags as potential releases:

datasette/.travis.yml

Lines 21 to 35 in 6151c25

	jobs:
	include:
	- stage: release tagged version
	if: tag IS present
	python: 3.6
	deploy:
	- provider: pypi
	user: simonw
	distributions: bdist_wheel
	password: ${PYPI_PASSWORD}
	on:
	branch: master
	tags: true
	- stage: publish docker image
	if: tag IS present

[simonw]

So I think if I push a tag of 0.45a0 everything might just work - Travis will build it, push the build to PyPI, PyPI won't treat it as a stable release.

Except... I don't want to push alphas as Docker images - so I need to fix this code:

datasette/.travis.yml

Lines 34 to 43 in 6151c25

	- stage: publish docker image
	if: tag IS present
	python: 3.6
	script:
	# Build and release to Docker Hub
	- docker login -u $DOCKER_USER -p $DOCKER_PASS
	- export REPO=datasetteproject/datasette
	- docker build -f Dockerfile -t $REPO:$TRAVIS_TAG .
	- docker tag $REPO:$TRAVIS_TAG $REPO:latest
	- docker push $REPO

[simonw]

Travis conditions documentation: https://docs.travis-ci.com/user/conditions-v1

These look useful:

branch =~ /^(one|two)-three$/
(tag =~ ^v) AND (branch = master)

[simonw]

So maybe this condition is right?

if: (tag IS present) AND NOT (tag =~ [ab])

[simonw]

I'm going to try this on a separate repository so I don't accidentally publish a Datasette release I didn't mean to publish!

[simonw]

https://github.com/simonw/datasette-render-images uses Travis and is low-risk for trying this out.

[simonw]

OK, I just shipped 0.2a0 of datasette-render-images - https://pypi.org/project/datasette-render-images/ has no indication of that:

But this page does: https://pypi.org/project/datasette-render-images/#history

And https://pypi.org/project/datasette-render-images/0.2a0/ exists.

In a fresh virtual environment pip install datasette-render-images gets 0.1.

pip install datasette-render-images==0.2a0 gets 0.2a0.

[simonw]

One more experiment: I'm going to ship datasette-render-images 0.2 and see if that works correctly - including printing out the new debug section I put in the Travis config here: https://github.com/simonw/datasette-render-images/blob/6b5f22dab75ca364f671f5597556d2665a251bd8/.travis.yml#L35-L39 - which should demonstrate if my conditional for pushing to Docker Hub will work or not.

In the alpha releasing run on Travis that echo statement did NOT execute: https://travis-ci.com/github/simonw/datasette-render-images/builds/172116625

[simonw]

https://travis-ci.com/github/simonw/datasette-render-images/builds/172118541 demonstrates that the alpha/beta conditional is working as intended:

[simonw]

Here's the Read The Docs documentation on versioned releases: https://docs.readthedocs.io/en/stable/versions.html

It looks like they do the right thing:

We in fact are parsing your tag names against the rules given by PEP 440. This spec allows “normal” version numbers like 1.4.2 as well as pre-releases. An alpha version or a release candidate are examples of pre-releases and they look like this: 2.0a1.

We only consider non pre-releases for the stable version of your documentation.

[simonw]

https://pypi.org/project/datasette-render-images/#history worked:

I'm now confident enough that I'll make these changes and ship an alpha of Datasette itself.

[simonw]

Alpha release is running through Travis now: https://travis-ci.org/github/simonw/datasette/builds/699864168

[simonw]

New documentation about the alpha/beta releases: https://datasette.readthedocs.io/en/latest/contributing.html#contributing-alpha-beta

[simonw]

This worked!

https://pypi.org/project/datasette/#history

https://github.com/simonw/datasette/releases/tag/0.45a0 is my manually created GitHub prerelease.

https://datasette.readthedocs.io/en/latest/changelog.html#a0-2020-06-18 has the release notes.

A shame Read The Docs doesn't seem to build the docs for these releases -it's not showing the tag in the releases pane here:

Also the new tag isn't an option in the Build menu on https://readthedocs.org/projects/datasette/builds/

Not a big problem though since the "latest" tag on Read The Docs will still carry the in-development documentation.

[simonw]

https://pypi.org/project/datasette/0.45a0/ is the release on PyPI.

And in a fresh virtual environment:

$ pip install datasette==0.45a0
...
$ datasette --version
datasette, version 0.45a0

But running pip install datasette still gets 0.44.