Prepare the project for publication on PyPI

[tucked]

This diff and the following steps will resolve #18.

You will need to install tox if you don't already have it. I recommend using the same steps outlined in Option 1 in the README.

1. Review and merge this PR.
2. Create an account on PyPI: https://pypi.org/account/register/
3. We need an API token to enable automatic publication, but we cannot create one until the project is created and associated with your account. So, the first time (only) we must publish manually:

   git fetch mhagger
   git checkout mhagger/master
   tox -e publish -- upload  # This will ask for your PyPI creds.
   

   • Note: This will publish a developmental release (because the version is generated from the nearest tag, and we haven't created a new tag since merging):

     $ tox -e publish  # Creates distributions for publication, but does NOT upload them.
     ...
     $ .tox/.package/bin/python setup.py --version
     1.2.1.dev6+gc97f5a6
     

     • That version is a PEP 440-compliant variant of git describe generated by setuptools-scm:

       $ git describe
       v1.2.0-6-gc97f5a6
       

     • pip install will ignore developmental releases unless the --dev option is passed (or the exact version is given).
4. The project should now exist on PyPI: https://pypi.org/project/git-when-merged/ That means we can now create an API token for it.
   1. Go to https://pypi.org/manage/account/ and scroll down to the "API tokens" section.
   2. Click "Add API token".
   3. Under "Token name" put something like "GitHub Actions" since that what we're going to use it for.
   4. Under "Scope" select "Project: git-when-merged".
   5. Click "Add token".
   6. PyPI may ask you to confirm your password.
   7. Click "Copy token".
5. Now we need to set the API token as a Repository secret for this repository.
   1. Go to https://github.com/mhagger/git-when-merged/settings/secrets/actions/new
   2. Under "Name", type PYPI_PASSWORD (as that is what the Publication workflow in this PR expects).
   3. Under "Value", paste the token we copied in step 4.vii.
   4. Click "Add secret".
   5. Repeat steps 5.i through 5.iv to set PYPI_USERNAME to __token__.

That's it for one-time setup! Now, new distributions will automatically be published whenever a Release is created on GitHub: https://github.com/mhagger/git-when-merged/releases/new

New distributions can also be published manually at any time using tox -e publish -- upload. The version that is published will depend on what is checked out when the command is run.

[mhagger]

Thanks!

I think that I'll skip the Actions automation; i.e., I'll end up merging the first three of your patches but not the fourth.

What is your rationale for requiring a minimum python version of 3.7? I believe that the code should work with Python all the way back to 2.6. I see that 3.7 is the latest supported version of Python; is that the reason?

Your instructions seem to work, except for checking the version with

$ .tox/.package/bin/python setup.py --version
1.2.1.dev6+gc97f5a6

First of all, the path .tox/.package doesn't even exist after running tox -e publish. The only python that exists is .tox/publish/bin/python. But running the command using that python version seems to consistently give version 0.0.0, regardless of whether there was a tag pointing at the checked-out version when I ran tox -e publish:

$ .tox/publish/bin/python setup.py --version
0.0.0

The files under .tox/dist/ do seem to have the expected version number in their filenames, though, so maybe this isn't a problem?

Thanks again for your help!

[tucked]

I think that I'll skip the Actions automation; i.e., I'll end up merging the first three of your patches but not the fourth.

👌 np. I'll remove that commit.

What is your rationale for requiring a minimum python version of 3.7? I believe that the code should work with Python all the way back to 2.6. I see that 3.7 is the latest supported version of Python; is that the reason?

The build tools require 3.7 (except wheel): https://github.com/mhagger/git-when-merged/blob/c97f5a6a76554737740633fd0054d81cd9302973/pyproject.toml#L2

Using older versions to get 3.5 or 3.6 support probably wouldn't be too hard, but getting them for 2.6 would be. Even supporting 2.7 usually requires some special handling...

First of all, the path .tox/.package doesn't even exist after running tox -e publish.

Woops, that's my fault... I forgot to update the instructions after adding this optimization: https://github.com/mhagger/git-when-merged/blob/c97f5a6a76554737740633fd0054d81cd9302973/tox.ini#L17

Usually, tox builds the project and installs it into the testenv before running the testenv's commands. Since the purpose of the publish testenv is to build the project, we don't need tox to also build it 😅 You should be able to create .tox/.package by running any of the other testenvs (e.g. tox -e static): https://github.com/mhagger/git-when-merged/blob/c97f5a6a76554737740633fd0054d81cd9302973/tox.ini#L5-L9

The only python that exists is .tox/publish/bin/python. But running the command using that python version seems to consistently give version 0.0.0, regardless of whether there was a tag pointing at the checked-out version when I ran tox -e publish:

The reason that happens is because publish (and indeed any other testenv) doesn't have the build tools installed by default. The build happens in an isolated virtualenv (.tox/.package if tox is doing the building) as described in PEP 517. The build tools are installed, and they are used to build one or more wheels. That wheel, along with any dependencies specified in install_requires, is what gets installed in the testenv. The isolated build env with the build tools installed in usually gets destroyed, although tox leaves .tox/.package in place.

The files under .tox/dist/ do seem to have the expected version number in their filenames, though, so maybe this isn't a problem?

Yes, that is because build used the PEP 517 build process I mentioned above: https://github.com/mhagger/git-when-merged/blob/c97f5a6a76554737740633fd0054d81cd9302973/tox.ini#L19 So the build tools were in place when those dists were created.

[tucked]

👌 np. I'll remove that commit.

It's over in my master branch in case you want it later.

[mhagger]

@tucked: thanks for all the help! :sparkles:

That kindof took me forever, but I have finally merged your PR along with a couple of minor tweaks and created and uploaded a release to PyPI. If you see any problems, please let me know.