Gin: [PROJECT] Future steps

[javierprovecho]

TL;DR

• API stability and deprecation policy
• v2?

---

cc @appleboy @tboerger @nazwa @easonlin404 @thinkerou

I'm worried on how to keep going and scale the API without breaking everything in a v2. Some people who use Gin love the new activity and features, but want Gin as it is now, somehow API stable. Others want a continuous development and deprecation of prior versions.

Because this is not JS, and there is no package.json pre-included, I see it's hard for beginners to understand the difference between go get ... and vendor/ folder and tools.

Projects that use Gin like drone-io have it vendor on a version from January 2016.

I was thinking on ways of allowing API changes with deprecation notices like it's being done now in deprecated.go.

An idea from the jsonite contribution and the build flags:

• added to *_experimental.go
• moved to *.go
• deprecated to deprecated.go (with printf warning)
• deprecated to *_deprecated.go (for very old builds)

I would like to know your thoughts on this, not just the idea above. Thanks 😃

PD: everyone is encouraged to participate too.

[sonemaro]

@javierprovecho If I'm not wrong, there is no way to show deprecated warnings in go. The only way is to begin a comment with Deprecated. The only way is to move it to something like this : v1/gin and mention it on README and create new one as gin

BTW, if you need a hand, I'm in for v2. We can talk on gitter or wherever you would like...

P.S: I'm sure you already know this. :-D. Just mentioned that...

[valasek]

TL;DR

• Name the core team
• Describe release, deprecation, security and code versioning rules which core team agrees to follow
• Stick with it and upgrade the rules when required

---

Below are a few thoughts and a proposal to stir the discussion. Elaborated rules can be published as a set of github wiki pages and linked from README and from a web site.

Core team

Usually appointed based on a project activity (number of commits, PRs, bugs, docs, responses, ... )

Based on commit frequency I see: @javierprovecho @appleboy, @thinkerou, @vkd probably missing others.

Release versioning rules

Go ecosystem adopted Semantic versioning. I propose to follow SemVer which is already part of the official go tooling.

Release frequency and quality

Time based vs. feature based releases are widely used.

Community examples

• Go release cycle - time based
• Django roadmap - time based
• Rails release history - feature based
• Debian releases - time based releases

I would like to see gin to adapt time based releases 1/2 year between minor version releases and 2 years between two major versions? So plan v2 on the beginning of 2020?

Define, how long each major and minor version will receive bugfix and security patches.

Supported release usually receives: Security fixes, data loss bugs, crashing bugs, major functionality bugs in newly-introduced features, and regressions from older versions.

Example from Golang

| Releases | Maintenance Starts | End of Critical Updates | End of Security Updates |
| --- | --- | --- | --- |
| Next | 1.12.x | February 2019 | August 2019 | February 2020 |
| Current | 1.11.x | 2018-08-24 | February 2019 | August 2019 |
| Previous | 1.10.x | 2018-02-16 | 2018-08-24 | February 2019 |

I can imagine that gin will receive security fixes in last two major releases and only latest minor version is supported. So if there is 1.4.0 and 2.0.1, after 3.0.0. release verison 1.x will not receive any security and bugfixes.

Deprecation policy rules

Use deprecation warnings comments in code. Hide deprecated things from GoDoc.

Community examples

• Django - is listing pieces which will be deprecated and in which release
• Go, marking deprecated structs.

Code versioning rules

TBD after release versioning is set.

Ecosystem

Once defined, this approach should be adopted by other gin repos and gin-contrib repos to create an healthy ecosystem.

[dmarkham]

Go ecosystem adopted Semantic versioning. I propose to follow SemVer which is already part of the official go tooling.

Getting on the current "official go tooling" and following SemVer :+1:

Time based vs. feature based releases are widely used.
I would like to see gin to adapt time based releases 1/2 year between minor version releases and 2 years between two major versions? So plan v2 on the beginning of 2020?

Time based does not feel like a good fit in my personal opinion. I would like to see Minor/Patch versions published when they are done not every 6 months. Major Releases should have goals for API changes / dates they want to hit but not strictly enforced. Go's new tooling makes moving from one release to another very easy. This should give us confidence people are not moving to a new release without knowing. Giving them the opportunity to evaluate the bug's fixes and features added on their own time frame. We should be giving them the opportunity to use a new features when they are done.

Use deprecation warnings comments in code. Hide deprecated things from GoDoc.

When not in release mode being noisy about methods being called in the logs with a recommendation/link/info to the new method/interface sounds like a great idea.

[thinkerou]

@valasek about release versioning rules, https://github.com/gin-gonic/gin/issues/1381 have part discuss, I agree with you, and I hope gin keep up with golang.

[montanaflynn]

Go modules supports versions now so that shouldn't be an issue anymore.

[phillipCouto]

Agree with @montanaflynn. This is a mood point now with go tooling finally supporting versioning of dependencies in a consistent way. Just outline the significance of the version numbers in the project and move forward. Also it would be great to specify how long a specific major version is planned to be supported. If you want gin to remain a viable web framework it needs to keep iterating and not be held back with concerns of breaking changes. If anything we can explorer going the angular root with upgrade automation to fix or identify deprecated API usage.

[axetroy]

Consider resolve Wildcard route conflicts with static router

Invalid router in current version

[GET] /v1/address
[GET] /v1/address/default
[GET] /v1/address/:id # conflict with `/v1/address/default`

[GET] /v1/user
[GET] /v1/user/profile
[GET] /v1/user/:user_id # conflict with `/v1/user/profile`

My Solution ❌

[GET] /v1/address
[GET] /v1/address/default
[GET] /v1/address/a/:id

[GET] /v1/user
[GET] /v1/user/profile
[GET] /v1/user/u/:user_id

I can't imagine how I endured such an ugly route.

I know this is a problem with httprouter implementation, but the related solution already has. ref: https://github.com/dimfeld/httptreemux

This problem has existed for 4 years and should be resolved.

[arianitu]

@axetroy if the documentation can actually have a notice that gin has this issue that would be great. I would never in a million years have picked the framework knowing that limitation. Please let potential users know that they will run into API conflicts with any complex API and will have extremely ugly routes.

Does anyone know how to use https://github.com/dimfeld/httptreemux in Gin?