Release Strategy and Versioning

[jpreese]

Right now each merge into master cuts a new release to NuGet. This is going to cause a lot of unneeded versions to be released and prevents us from putting together a more holistic release.

Versioning is also driven from the appveyor config file -- I'd like to see versioning driven from the releases page and tags so we're not having to redeploy the config file for each release. This also means we can get away from having releases with build numbers, and lean more on semver and bump the release numbers as needed.

We can take this a couple of ways.. we can modify the appveyor config to only release on tags, so we have the ability to merge into master without firing off a release. Or we could merge into a release branch and only merge into master when we feel we have enough content for an actual release.

I lean more in favor of cutting releases when tags are pushed.

With all of that in mind, just wanted to leave this here for a little bit of discussion before going forward.

[tathamoddie]

What's the problem with too many versions? If each little bit moves us forward, what's an "unneeded" version?

When it comes to SemVer, the API surface is incredibly stable: it's defined by .NET and only has immense backwards compatibility. Thus, the major version is almost never touched anyway.

I like SemVer, I just think we get a lot of it for free here in this particular library context.

I also hate the idea of ever bundling up unshipped work and delaying it until the next 'release' event. NuGet packages are free. Ship a million of them!

[jpreese]

I'm not entirely opposed to the current strategy, it's obviously worked for this long. To me an unneeded version would be say, the license change to MIT. There's really no value in bumping that up as we didn't really change anything. Though those types of merges are going to be rare. Maybe even pure refactorings where we introduce no new features or bug fixes.

I mostly approached it from the idea that if I'm a consumer of the library, and I want to update my project that uses it. I need to redeploy my app. If I want to stay current, that could be everyday.

I completely agree about wanting to ship something as soon as it's ready, but cases where we have multiple PRs to merge.. each merge will be a new version vs. combining them into a singular release. We don't delay the release, just consolidate. Though we could do this today already with some form of a release branch.

TLDR if you're ok with it, I am. There's a lot more issues out there that need attention instead of versioning.

My parting question would be, when do you typically update the minor or patch numbers in the version? Right now, I'm not certain of the criteria.

[tathamoddie]

The license change legitimately triggers a different package: some people might want to update to MIT immediately, and have it in their app as that.

[tathamoddie]

I bumped the major version when I broke something on the build server and stuffed a version number.

I think I last updated the minor when shipping a big batch of Unix support.

As long as each update adds to the API surface, or targets, I don't think either number needs to change again. Maybe something big like adding .NET Standard 2.0 support, would increment the minor? The main API is defined by System.IO, which is one of the slowest and most stable around.

[jpreese]

Alright the last point I wanted to bring up for clarity is that if we continue the approach of just releasing on merge, do we have a plan for any sort of CHANGELOG / release notes? Or do you feel given the project and how it's used, there isn't much value to it.

[jpreese]

After mulling it over, I think I'm OK with just releasing from the hip. I like the way you phrased it with System.IO is our API, so technically we should just be a 1 to 1 in functionality. Not really introducing anything "new" or "breaking".

Sure, we'll fix bugs and add in unimplemented members, but the person who originally reported it is the one who is going to care right then and there. Once it's merged, there's their notification.

[tathamoddie]

On the surface, it feels under-baked compared to every other library out there and all the work they do around release management / versioning, etc., but I think the System.IO attachment actually makes it quite simple for us. Definitely good to have re-visited this with another set of brain cells though. 👍