Go API Version Documentation

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.

Hi @Rheza,

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.

@christophberger I know that we have changelog and go doc time package - time - pkg.go.dev.

But I would like to understand more why don’t we add useful information in code doc itself go/time.go at master · golang/go · GitHub

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.

1 Like

There is another trick that you can use in pkg.go.dev

https://pkg.go.dev/time@go1.18beta1?tab=versions

When the API changes, there will be a diff(default is not expanded). You can click “Expand All” to check the API/Data struct changes.

1 Like

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.

@christophberger I believe it’s not XY Problem, due to the nature that others langs are doing it also without a problem (self opinion).

In long term, Go will add more functions / deprecations, currently the list is maintained in here go/api at master · golang/go · GitHub

However, as the list getting bigger, you probably need to add Go version in function comment doc for 2 reasons:

  1. Make your intention clear toward function changes, and track history.
  2. Easy to look up and pretty straightforward when you browse code.

I still don’t see the purpose of this requirement.

  1. “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.

  2. “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?

  3. “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?

Godoc (not go doc) has a Web mode:

godoc -http=localhost:6060

Would that help?

@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?

Thanks @Rheza and @NobbZ to help me understand the background of the request.

I am afraid I cannot help much beyond suggesting godoc -http, so maybe you want get in touch with the Go team.

To get started, here are two issues I found in the Go repo mirror at GitHub:

x/tools/cmd/godoc: show which version of Go introduced symbols · Issue #5778 · golang/go

And a follow-up to implement that for cmd/doc:

cmd/doc: show which version of Go introduced symbols · Issue #29204 · golang/go

Fun fact: the info appears to exist in the online docs already, see e.g. the unsafe packages that got a few new function in Go 1.17.

Screen Shot 2022-01-24 at 14.58.11

1 Like

I’m aware of this. Please see my previous comment.

That’s not what I tried to propose, but rather “inlined code level” doc of Go version. The one that you showed is taken from Api changelog file.

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.

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.