v2: decide on import path and make a new release

[kolyshkin]

The latest release is from September 2018, maybe it's time to make a new one?

The primary reasons for a new release are #509 and #515; this will make the package not depend on any other packages. Including #586 would be nice, too.

[dmitshur]

This should be done.

In order to be able to publish new v2 versions, a blocking task is to resolve the current lack of clarity about what import path should be suggested and continued to be used for v2: github.com/russross/blackfriday/v2 or gopkg.in/russross/blackfriday.v2. The go.mod file says one thing, the README on master branch says something that isn't very consistent.

By making a newer release, some decision would be committed to, and ideally that decision should be a good one given the constraints this project is currently operating with. Some of the decisions made in the past predate a good understanding of modules and best practices regarding v2 versions, which has made this decision more difficult to make conclusively.

I suspect that in the current situation, the best course of action is to continue to use the github.com/russross/blackfriday/v2 import path, as defined by the module statement in go.mod file in v2 branch:

blackfriday/go.mod

Line 1 in 3b2b20c

module github.com/russross/blackfriday/v2

I started talking to @rtfb about resolving this situation a number of months ago, but then unfortunately dropped the ball on it due to lack of bandwidth. But I wanted to post this comment to shed light on what I believe is a large contributing factor to no new v2 releases.

[russross]

I'm happy with either import path and agree that we should post a new release soon. I haven't been following developments in the module system very closely--is there one approach that is more forward looking/will fit in better with the community than the other?

[SamWhited]

There's also a third option which I always personally prefer: using a new vanity import path (eg. blackfriday.example.net/v2).

This requires that someone own a domain name and setup an HTTP server (or use a service like Netlify or GitHub Pages) which is more work for the maintainers, however, it gives you the benefit of owning your package import instead of relying on GitHub or gopkg.in never changing or going under or being changed to github.microsoft.com or similar. While this may not seem likely, other scenarios could be imagined where GitHub becomes impractical in the future, for example a price change, adding more extreme rate limiting that causes fetching packages to break more often, the author just decides they don't like GitHub and want to use , etc.
Using a vanity import keeps things flexible in the future, and avoids unforeseen future issues at the cost of a tiny bit of infrastructure work. I would be willing to help set this up if you want.

[kolyshkin]

This requires that someone own a domain name and setup an HTTP server

... and in a couple years it will be down and we won't be able to reach a person who hosted it. Speaking from experience :-\

[SamWhited]

I would think relying on GitHub would be the bigger risk here. They could go under, or Microsoft could change their pricing and make it harder for open source projects to host on it, or some overzealous company could file a patent claim against something as trivial as tree traversal and Microsoft could take down the repo out of an abundance of caution, etc.

The package proxy smooths out this sort of thing either way though.

[russross]

I'd rather stick with github. It's pretty standard and predictable without requiring any maintenance. The Go project is hosted there as are most libraries in widespread use, so in the unlikely event that Microsoft pulls the rug out from under everyone, updating blackfriday will just be a small part of a much larger disruption.

[laher]

Assuming that we don't need to debate the module path any further ... I believe all this really needs is a README update to replace the 'gopkg.in' recommendation, and a tag on the v2 branch - v2.0.2/v2.1.0?

Or, are you considering a merge into master first?

If it's just the tag & readme, I can make a PR for the readme update.

FWIW I agree that github seems the pragmatic choice - I don't believe blackfriday has any need for gopkg.in any more now that modules have versioned paths - and also hasn't github already been chosen in go.mod, in both the v2 branch and the v2.0.1 tag?

[mwat56]

@laher

Assuming that we don't need to debate the module path any further ... I believe all this really needs is a README update to replace the 'gopkg.in' recommendation, and a tag on the v2 branch - v2.0.2/v2.1.0?

… and copy the recent files to a ./v2/ subdirectory while leaving the v1.x.x files were they are. (see Go Modules: v2 and Beyond )

[laher]

@mwat56 it's worth raising that point, yup, especially this part:

if v2+ source code is on the repository's default branch (usually master), tools that are not version-aware — including the go command in GOPATH mode — may not distinguish between major versions.

I guess the question is, would it be OK to just break non-module-aware users that aren't pinning versions somehow? And, I guess the answer for such an established project like blackfriday, might be 'nope, not for some time to come'? Or not? pained thinking emoji

[mwat56]

@laher

[...]
I guess the question is, would it be OK to just break non-module-aware users that aren't pinning versions somehow?

Why break anything at all? Just leave the current files as v1.x.y and copy the newest version of each file into a new subdirectory ./v2/ and assign there a version tag v2.x.y

That way the non-version aware projects (are there still some of those after discussing versioning for years?) are using the v1.x.y and the version-aware projects can use the v2 branch if they want.

Sure, it will probably take an hour to do the copying and check-in into a new v2 branch. But in the end all those require/replace hacks won't be necessary anymore.