In Language like Java / C#, we have the API versioning for newly introduced API / function.
However, apart from Changelog, I don’t find any documentation related to the API.
For example, in time package, there is new method UnixMili() introduced in Go 1.17 api: audit for Go 1.17 · Issue #46688 · golang/go · GitHub. But in API method I couldn’t find any doc explaining when or since what go version UnitxMili() API being added.
I think this sort of documentation is needed to understand the std lib changes.
Updates to the standard library happen in sync with new Go versions. Therefore, all updates to the stdlib are documented in the Go release notes.
Side note: if you need to know when a feature was added to the stdlib, you are probably stuck with an old Go version - perhaps unnecessarily. Go has the Go 1 Compatibility Promise to make keeping up with the latest Go toolchain as straightforward as possible. TL;DR: old Go code should run unchanged with the latest Go 1.x version, with rare exceptions like breaking security fixes.
This will avoid cluttered doc about changed functions. Something like (taken from release doc)
go1.17.2 (released 2021-10-07) includes a security fix to the linker and misc/wasm directory, as well as bug fixes to the compiler, the runtime, the go command, and to the time and text/template packages. See the Go 1.17.2 milestone on our issue tracker for details.
it is not self explanatory to explain added/changed methods/functions.
Usually when I code, I will go to code documentation itself rather than changelog. I believe that’s what most developers also do.
My point is, if you / GO maintainers could consider to add (since) when this method is added in the code comment, it’ll be useful for everyone else understanding the changes.
I will not take credit on my proposal. The decision is up to you.
My main point here is, why couldn’t I see the go version when this method being added in source code doc itself (like this method go/time.go at master · golang/go · GitHub) ?
What’s stopping us to see the go version in the method doc?
Just for the records, this is not an official Go forum, and most of the people that hang out here are Go users like you and me. If you want to get hold of Go maintainers, the Google group golang-nuts might be a good place to start.
Regarding your request, why do you need to know this?
I am asking because the need for changelog info in the code might be an XY problem.
I still don’t see the purpose of this requirement.
“Make your intention clear toward function changes” - I cannot see how the code docs are the right place for discussing intentions? Intentions are discussed inside proposals, drafts, and issues.
“Track history” - agreed but why inside the code docs? Why is the changelog not enough? For which kind of development requirement do you need to look up historic changes while coding?
“Easy to look up and pretty straightforward when you browse code” - again, when would you need this?
What real-world problem exists that would make documenting the history of code changes inside the code docs a necessity?
As someone who uses elixir and python as often as go, and also being forced to use certain old compilers/runtimes of either, due to customers requirements/enforcement/whatever reason, I know how elixir and python handle added or changed API and I know how golang handles it, and I fully support the request!
Elixir has documentation metadata, a clear since x.y.z
in the functions/macros head shows since when functions and macros are available, python also usually has some clear paragraphs about a methods history, sadly often hidden in prose, but still available.
For go, the only way to know if a certain method/type/function/interface is available in a certain version of go, is to have that version installed and use go doc or have a HTML document prerendered locally that matches that version.
Rust (which I use in conjunction with elixir often), has similar, if not stricter, compatibility guarantees than go has, and even they clearly annotate if a function/method/etc has only been added from a certain version on.
Thanks @NobbZ. I am genuinely curious: In what situations is go doc of the installed version not enough? When do you need to query the stdlib history of changes outside an actual project?
If you need to keep your code compatible with some previous Go 1.x version, then I see no way around actually using that particular Go 1.x version for developing that code, or otherwise your code might run into subtle bugs that existed in that version but not in the current toolchain, despite the compatibility promise.
Example: The Go scheduler became preemptive in Go 1.14. Identical code behaves differently when compiled with Go1.14 or later versus prior versions. Ok, that’s not a stdlib API but my point is, if code needs to run on a historical Go version it needs to be developed and tested with that version.
Edited to add: But I am aware that I might completely miss a point that is totally obvious for others in similar situations as you. If missing version information of the stdlib API is indeed a serious obstacle for daily development (rather than being a solution in search of a problem), I’d suggest discussing that request on golang-nuts - Google Groups – you should find a few people there who are close to, or even part of, the core Go team.
Yes, I have to have it installed either way, still browsing the documentation on a website is much easier, and to be honest, I have some coworkers that do understand that they have to target go 1.10, but not that they shall use go doc on the terminal to read docs. Even less do they understand that they can run a local documentation server. They have a bookmark for the canonical documentation which misses crucial information.
Also the problem wit using go doc on the terminal is, you need to know the function before hand, you can not search the API as you could with a website.
The main question we want to have answered from the canonical documentation is: is this documented piece of API available to me in the version I have to use?
@christophberger I think @NobbZ has valid point about doc comparison between Elixir, Rust, and Go, or even Java.
This is what the thread intent after realizing Go changes when upgrading Go 1.15 to Go 1.17.
Yes! you are right, you can find the doc in web via godoc, but it’s not enough, if someone read the source directly.
As I said, it’s sad but true, but there are devs who have a problem doing so. Be it because they don’t remember to start the server before, or e it because localhost isn’t the canonical bookmark anymore.
I fully understand though, that this forum is not the proper place to discuss or propose this, though perhaps here are people that would support a proposal?
Understood. As I wrote, the best option is probably to ping golang-nuts. Personally, I think that version info in the docs is sufficient - see the screenshot in my last update. Using the stdlib API does not require reading the source code.
