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.
Comment From: 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...
Comment From: 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 |
| Current | 1.11.x | 2018-08-24 | February 2019 |
| Previous | 1.10.x | 2018-02-16 | 2018-08-24 |
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.
Comment From: 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.
Comment From: 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.
Comment From: montanaflynn
Go modules supports versions now so that shouldn't be an issue anymore.
Comment From: 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.
Comment From: 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.
Comment From: 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?
Comment From: atlance23
@javierprovecho can you explain to me what the issues are with API stability in Gin? I'm wondering if I could write a library that could be pulled as a dependency in Gin for depreciation warnings. I am still a go paddywan so anything I can learn is much appreciated!
Edit: Accidently said Go instead of Gin