Prepare v0.17.0 release

[joshuagl]

Description of the changes being introduced by the pull request:

Add CHANGELOG entries and bump version numbers for a 0.17.0 release

Please verify and check that the pull request fulfills the following
requirements:

• The code follows the Code Style Guidelines
• Tests have been added for the bug fix or new feature
• Docs have been added for the bug fix or new feature

[joshuagl]

This release should also include the sslib bump in #1285. I'll update this PR to mention it.

[joshuagl]

Thanks for the review @jku! I've just force pushed a new version of the patch which includes #1285 (not yet approved/merged) in the changelog.

[lukpueh]

Should we add max version constraints to requirements.txt and setup.py? Without constraints people won't be able to install TUF 0.17.0 dependencies on Python 2.7 as soon as any of the dependencies releases a newer version without Python 2.7 support.

[joshuagl]

That's a good point. This might be a good justification for a release branch too, as dependencies drop Python 2.7 support we can add the max version constraint in the release branch for people who continue to use Python 2.7.

[joshuagl]

I think that would mean that we would have to list our transitive dependencies in requirements.txt

[lukpueh]

I think that would mean that we would have to list our transitive dependencies in requirements.txt

Agreed. requirements.txt and requirements-pinned would list the same dependencies but with different constraint markers.

# in requirements.txt

dependency1 < X.Y.Z    # no py2 above X.Y.Z
dependency2            # hasn't dropped py2 yet

# in requirements-pinned.txt 
dependency1 < X.Y.Z      # ignored by dependabot 
dependency2 == Y.V.W.    # bump with dependabot until py2, then constrain here and in requirements.txt

This definitely calls for a py2 branch

[MVrachev]

What are the advantages of having a release branch compared to what we do now?

[joshuagl]

Once we make the release we don't want to add any new features for Python 2.7, only fixes. If we do need to add fixes for Python2.7 we can create a branch at the point we tagged the release and add fixes there which are likely to be changes that don't exist in the develop branch, or changes implemented differently to similar changes in the develop branch.

We would usually release fixes and features together in a new release, the release branch enables us to release fixes without features and without having to hold features from landing in the develop branch.

[jku]

I guess these decisions are mostly up to whoever cares about and maintains the 0.17 (or python2) branch.

Or is there a suggestion here that we should do something now, before this release?

[joshuagl]

I guess these decisions are mostly up to whoever cares about and maintains the 0.17 (or python2) branch.

Or is there a suggestion here that we should do something now, before this release?

I think @lukpueh's concern is that if we don't do something before the release, then a pip install tuf with python 2 can easily be broken when one of our dependencies (direct or transitive) updates and drops Python2 support.

I think the only way to resolve this is to list version constraints in our setup.py, because the install_requires lines in the setup.py are what pip uses to install dependencies [1].

[lukpueh]

That was indeed my concern, @joshuagl. And, yes, we'd need to do in setup.py what I sketched out for requirements.txt above. We can even get rid of requirements.txt.

I'd still keep requirements-pinned.txt though, to track any future py2 drops in direct and transitive dependencies, using Dependabot and automatic builds, so that we can little by little constrain all direct and transitive dependencies in setup.py in future patch releases on a py2 release branch.

Alternatively, we can add all direct and transitive dependencies to setup.py and constrain them right away, and really make this the last Py2 release period. This would mean no more py2 work for us, which seems reasonable, but also doesn't allow py2 tuf users install any newer dependency updates that might still support py2.

[jku]

How does Coveralls integration work?

The checks are done in the CI workflow (once per build) and then some finalize step in the end. But:

• why did two of those builds lead to a special "Coveralls" item on the check list on this page (but others did not)
• why does one of them claim to be a failure?

[jku]

How does Coveralls integration work?

The checks are done in the CI workflow (once per build) and then some finalize step in the end. But:

• why did two of those builds lead to a special "Coveralls" item on the check list on this page (but others did not)
• why does one of them claim to be a failure?

I see this issue even on merges to master: I'll file a separate issue. It should not stop the release, this is likely an infra issue

[lukpueh]

How does Coveralls integration work?

The checks are done in the CI workflow (once per build) and then some finalize step in the end. But:

Yes, that's how it works.

• why did two of those builds lead to a special "Coveralls" item on the check list on this page (but others did not)

I have no idea. None of the other pending PRs have those items. However, if I look at the "Status checks found in the last week for this repository" in the "Branch Protection Rules" in the repo settings, there's a check for each build of the ci matrix.

In the coveralls.io settings, there's a "USE STATUS API?" checkbox which is checked. I guess I could just uncheck that, so that it doesn't bother us?

• why does one of them claim to be a failure?

I don't know. There are no values for "COVERAGE THRESHOLD FOR FAILURE" and "COVERAGE DECREASE THRESHOLD FOR FAILURE" in the coveralls.io settings. I do have a faint memory that they just assume (but don't show) default values, if none are supplied. Couldn't find anything in the docs though.

[jku]

Taking the python2 discussion out of the subthread: it's not really about the patch.

I think @lukpueh's concern is that if we don't do something before the release, then a pip install tuf with python 2 can easily be broken when one of our dependencies (direct or transitive) updates and drops Python2 support.

I mean, yes it could theoretically be broken if the application developer doesn't pin the releases of the obsolete software he wants to use: I'd argue it's his job... I'm not sure we (who are not interested in running/maintaining/testing obsolete software) are going to be better at maintaining the pin list than the people who are interested in using obsolete software.

---

That said I guess we can make this discussion a little more practical.

  install_requires = [
    'requests>=2.19.1',
    'six>=1.11.0',
    'securesystemslib>=0.18.0'
  ],

Out of these securesystemslib should be good now, right? There is a version that supports python2 and future version don't so they won't get pulled in. I don't think six is going to drop python2 support 😁. requests seems to work like securesystemslib: latest version explicitly does not support python 2.7 but there is a version that does.

So direct dependencies seem covered: they cannot break (let me know if there's a flaw in this logic). EDIT: seems I misread requests status: they do still seem to support 2.7 in latest release

So the possible issues would be transitive dependencies... I guess I can do the same analysis to those.

[jku]

OK: I looked at all the dependencies. There are still a surprising amount of projects where the python2 strategy has not been publicly decided.

These support py2 and always will:

subprocess32
enum34
ipaddress
six

These have already moved to py3 only:

idna
cryptography

These have made the change in master or are expected to do it next release

securesystemslib
chardet
urllib3

The rest are "undecided":

pynacl
cffi
pycparser
requests
certifi

Nevertheless: I believe if the new releases of dependencies are correctly packaged (they set python_requires correctly), the correct versions should get installed (this means there actually was an extra requirement in my recent cryptography change in SSLib: pip will figure out that cryptography 3.4 can't be installed on python2 without us saying so in setup.py).

So us pinning maximum dependency versions in our setup.py would be covering for errors made in the depedency packaging. I suggest we don't do that except in specific cases.

[lukpueh]

So us pinning maximum dependency versions in our setup.py would be covering for errors made in the depedency packaging. I suggest we don't do that except in specific cases.

You are absolutely right. I didn't think of the (in my defense relatively recently added) python_requires field. It should help us here.

[joshuagl]

Thanks for the detailed investigation @jku. If I am following things correctly, I think we are good to merge this PR and make a release?

If pinning dependencies (direct or transitive) is required for Python 2.7 support, we can help someone to create a release branch and handle the required changes to setup.py there.