Cleanup for pull requests and versioning policy.

[lizroth]

Included in this PR:

• Adding our PR template
• Adding explicit callout of our dependency version change behavior
• Adding Z version change notice for upcoming breaking changes, where possible
• Try to simplify some language in VERSIONING.rst

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[mattsb42-aws]

I think it would be good to explicitly differentiate these breaking changes from the breaking changes for which we will introduce major changes.

Maybe Less significant but backwards incompatible changes?

[lizroth]

The current language, after review/discussion with @juneb is:

Possible backwards-incompatible changes. These changes will be noted and explained in detail in the release notes.

My small pushback is that minor changes are already described as "moderate", less significant than X changes, just above. Reiterating that in the bullets adds grok friction; if it's meaningfully clearer/more explicit I'm cool with that, though.

My goal is to keep this as quick and easy to understand as possible for customers.

[mattsb42-aws]

Fair enough. I think when I got into the inner bullet points my brain lost context that we had already stated that they were moderate changes.

[mattsb42-aws]

declared dependencies or dependency versions

Just to be explicit.

[lizroth]

This is the old language, there's a few changes since. The newest version is:

Any change to the version of a dependency.

Is that clear enough or would you still prefer changes?

[johnwalker]

Do we do a minor rev on patch changes to dependencies?

[lizroth]

Under this contract, yes.

That seems sensible to me for the following reasons:

1. Versioning policies differ from dependency to dependency, so we can't make reliable predictions on how our dependencies will change, only on how we'll notify our customers of changes.
2. Dependency updates tend to happen in clusters, so I expect to see things like 2-3 dependencies having patch rev updates in one of our changes.
3. Part of the goal here is to be clear, predictable, and as safe as possible. Changing dependencies always carries some risk. Doing a minor version rev every time adds some noise, but provides a reliable, clear bound and helps ensure Z updates are always safe.

[mattsb42-aws]

Following on from this morning's discussion, if we want to start being more prescriptive about our stated support for max versions as well, then I think what we're wanting to convey here is that we will minor version bump on two events:

• we change the required minimum version of a dependency
• we introduce a new dependency

Though in writing that up, I remembered that Maven only supports explicit version statements, not ranges...

[lizroth]

if we want to start being more prescriptive about our stated support for max versions as well

If we do, then why wouldn't we change the minor version if we change our max supported version of a dependency? That's a change to what we support that can cause integration work for customers, if we need to (for example) pin to an earlier version of a library pending a fix.

All of these cases seem to me like they still fall cleanly under "Any change to the version of a dependency.", which is also language/platform/packaging system-agnostic.

[mattsb42-aws]

What I worry about there is the different release cultures that different languages have and how that will affect the versioning we advertise. If we assume the dependency releases are rare, then sure, any changes to advertised support for dependency versions should be fine. But if dependency releases are frequent and we want to be explicit about what dependency versions we support, I worry that bumping the minor version every time that advertised support set changes will result in our minor version changes becoming frequent events, and in turn making it more difficult for consumers of our libraries to keep up to date.

I guess this also stems from the very different ways that dependency versions are handled in different languages and distribution systems. For cases like Maven where we explicitly state the version we expect, the relationship is necessarily much different than cases like common PyPI usage where we instead state a closure of versions that we expect to work.

[johnwalker]

No more concerns from me!

[lizroth]

But if dependency releases are frequent and we want to be explicit about what dependency versions we support, I worry that bumping the minor version every time that advertised support set changes will result in our minor version changes becoming frequent events, and in turn making it more difficult for consumers of our libraries to keep up to date.

True. At this point, as far as I know, we can't predict that, though. If it becomes a problem, we can explain the problem, apply an appropriate fix, and move forward. It won't be a surprise, because we've already stated in the guidelines we started with that we'll announce it, and we will in a predictable way. I don't mean this lightly; harm reduction is at the front of my mind here, and I know this has the potential to cause upgrade pain. I'm trying to optimize for best outcomes with imperfect information.

If you already know of a case coming up where this is going to be a problem, then let's block on it. If this is a weakness we could bump into, but is currently only a possible occurrence, then I'd say let's get started and address it when we have more information.

Currently we don't provide guidelines for how we'll handle version changes, so the status quo is less predictable for various version management scenarios. There's a good argument for keeping it less specified (that I think you're alluding to), but dependency versions is a common enough thing to manage (and one we've run into already) that it seemed to me worth including.

[mattsb42-aws]

Ok, that sounds reasonable. I don't have a hard example, just anticipations. We can always make things less restrictive in the future if it ends up being a problem, so I think for now I'm happy with this.

[lizroth]

Confirmed with @juneb out of band as well.