proposal: compiler warnings for deprecated / soon to be shutdown features and GOEXPERIMENTS

[nikolaydubina]

Proposal Details

I know go maintainers do not care and will dismiss this proposal, as they usaully do. but adding this for collective history. (unless they will start removing discussions they do not like entirely).

go 1.27 fiasco with GOEXPERIMENTS=jsonv2 that dropped format tag is not good.

major reason why it makes especially bad is that people who opted-in DID NOT KNOW that the flag will be shut down in 4 months. unless you follow go threads or some personal blogs or all of the github issues, people do not even know that experiment is shut down.

other languages have compiler warning mechanism:

• Kotlin has compiler deprecation warnings
• Swift has compiler deprecation warnings
• Rust has compiler deprecation warnings
• Typescript has compiler deprecation warnings

Go does not.

if you have some expected change in behavior (particualrly important for GOEXPERIMENTS), there is no way for people who opted-in to be notified what is going on.

then suddenly, out of blue, you get your code crash. and maintainers just shrug "there is no compatibility promise. it is experiment."

right, but how people know what is going on with these experiments? not everybody is reading all threads / emails / zoom calls in what go core team is doing.

the fact that there is no notification / warnings static analysis mechanism is bonkers.

[nikolaydubina]

how to make it better:

timeline:

1. 2025-08 go1.25.1 go jsonv2 format is introduced
   ..
   ..
   ..

2. 2026-05 go team plans to shut down format

3. 2026-06-02 go1.26.4 (could have been added here compiler warning)

4. 2026-07-07 go1.26.5 (could have been added here compiler warning)

5. 2026-08-13 go1.26.6 (could have been added here compiler warning)

6. 2026-08-19 go1.27.0 format is broken

information about decision was months in advance. it could have been added into static analysis go vet / go compiler to warn about this flag.

this should clearly visible to people who activelly using this flag what is going on and be prepared, digest, stop using this flag, and start moving away from it.

[nikolaydubina]

effectivelly, people learn about this feature 1 year ago, start using it. follow for couple months development and progress, and move on. then it is down all of sudden a year later.

it is like you did not even know that it will be shut down and continue using it given past memory that it was ok.

[nikolaydubina]

how did our project learn that format is not supported anymore?

1.27 compiled with no issues and started to error out at runtime.

[gabyhelp]

Related Documentation

• Go Wiki: Prior Discussion > Asked Questions & Prior Discussion > Add warnings to the Go compiler

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[nikolaydubina]

Experience in large projects has shown that warnings pile up until people ignore all warnings, so warnings only add noise and no value (or are actively harmful in that they hide bugs). See https://go.dev/doc/faq#unused_variables_and_imports

totally opposite.

1. helps communicate upcoming derpecations
2. bring up possible issues to attention (opposite of "hide bugs")

otherwise, copiler did not error, no warnings anywhere. and code is broken at runtime after 1 year of working with no notifications from compiler, and you only have to ask AI and in forums "what is going on? where did that feature go? what do I do now? oh there is some flag ("jsonformat") to keep it alive? nope, it does not work either..."

how come Go got this is so backwards?

[rsc]

GOEXPERIMENT is for experiments, and experiments change and break. If you opt in to one, you take on that risk. I am not sure what the exact complaint is here. Did we do something wrong with jsonv2?

[prattmic]

other languages have compiler warning mechanism:

• Kotlin has compiler deprecation warnings
• Swift has compiler deprecation warnings
• Rust has compiler deprecation warnings
• Typescript has compiler deprecation warnings

If you have references to how other languages handle changes to or removal of experimental features, that would be useful to hear. I'm not familiar enough with these ecosystems to know the details on handling of experimental features.

For example, in Kotlin, stability level "Experimental" sounds like the closest parallel to GOEXPERIMENT. Its doc states "the feature may change or disappear at any time. We don't guarantee stability or compatibility." The removal process is not documented, so it's not clear what the policy is.

In Rust, "unstable" features are the closest parallel to GOEXPERIMENT. I haven't found official policies for these, but they appear to (at least sometimes) be simply removed wholesale with no warning, such as rust-lang/rust#141811.

---

Regarding your proposal to include some form of warning in minor releases:

The format tag was removed in https://go.dev/cl/773980 (2026-05-05). Realistically it could have been removed as late as the release freeze (2026-05-20), or perhaps slightly later for API review.

If we were to include a warning in the next minor release, that would be have been Go 1.26.4 (2026-06-02) or perhaps Go 1.26.5 (2026-07-07) if the removal was very late.

This would have provided up to 2.5 months of notice ahead of the Go 1.27 release. Would that have made a big difference? I'm personally a bit skeptical. If you depend on this feature, you have until 1.26 loses support to migrate off of it. That is 6 months from today. With additional notice, it would have been 8.5 months. Additional notice is always nice, but if 6 months isn't enough, would 2 more help that much?

We released Go 1.27 RC1 on 2026-06-18. At this point, it was straightforward to test for compatibility (GOTOOLCHAIN=go1.27rc1 go test ./...), so this also should have provided 2 months of notice. Go 1.27 RC1 also comes with the full release notes. We don't currently list changes to GOEXPERIMENTs in the release notes, but I think that would be something that makes sense for #80969.

---

To Russ's point, we really don't intend GOEXPERIMENTs for production use, especially GOEXPERIMENTs that preview an unaccepted proposal. The intention is for limited experimentation and feedback on the proposal. So rather than smoother deprecation of GOEXPERIMENTs, my first inclination is to figure out how to better discourage production use. If we had better canonical documentation for GOEXPERIMENTs (#80969) that clearly laid out not to use them in production, would that have stopped you from taking a dependency on GOEXPERIMENT=jsonv2?

[nikolaydubina]

thanks for details.

I think you are both right. there is misscommunication here. over last year amount of talks in community "hey try this out! GOEXPERIMENT=jsonv2!" was on rise. countless blog posts and talks. you try it for couple months, follow progress, and move on. and then year later or so it will break (potentially dangerously). I doubt I am the only one got burned on this one.

yes. some statements "can be deprecated without notice", would be good to stop and think not to use it.

---

Swift. it shows up warnings when you compile, shows up in XCode UI over code.
this leaves us time to be aware of change is upcoming and leaves room to prepare for it.

https://docs.swift.org/compiler/documentation/diagnostics/deprecated-declaration/

I would expected something similar from GOEXPERIMENTS deprecations. but I was wrong.

There are also Swift core experimental features, but that requires separate toolchain and is not easily avaialble in released compiler/XCode. For Go json, it is available in production compiler, so not as clear if we should have either: A) expect Deprecation notices (turns out no!); B) expect failure at any time. In released publicly Swift toolchain, you would get warnings in UI/compiler. For hidden features that are unstalbe, you need separate toolchain so you could not access those either.

maybe GOEXPERIMENT should be in release candidates only? so that people do not confuse stable and unstable toolchains? that will help.

[gopherbot]

Change https://go.dev/cl/819120 mentions this issue: _content/doc/go1.27: mention some changes to GOEXPERIMENT=jsonv2

[thepudds]

Hi @nikolaydubina, FWIW, I sent https://go.dev/cl/819120 to update the Go 1.27 release notes to mention that format tag option was removed along recording some other notable json/v2 GOEXPERIMENT changes that happened.

Separately, linters can be helpful as well for things like this.

I'm not deeply familiar with the SA5008 "Invalid struct tag" rule in staticcheck, but as far as I can tell from a quick look, it seems to still treat format as a valid tag option:

https://github.com/dominikh/go-tools/blob/2026.2.1/staticcheck/sa5008/jsonv2.go#L170-L174

If you are interested, perhaps you (or someone) could investigate that a bit further to understand the current state of that, and/or consider filing a suggestion on the on the staticcheck repo if there isn't one already. (Also, note that staticcheck is separate from the Go project and it is a volunteer effort by one person). Alternatively, maybe some other linter like revive might be interested.

Finally, you are probably aware, but Go does have some support for deprecations in general. I don't believe that directly supports struct tags, but it does support things like the Swift RollBarConfiguration API deprecation you showed above.

[thepudds]

Also, as part of trying to pull together a list of json/v2 GOEXPERIMENT changes, I also went back and skimmed some of the various statements made by the people working on json/v2 to see what had been said regarding the stability of the API.

For example, from the json/v2 blog (just after Go 1.25 was released):

The nature of an experiment is that the API is unstable and may change in the future.

And from the Go 1.25 release notes:

We encourage users of encoding/json to test their programs with GOEXPERIMENT=jsonv2 enabled to help detect any compatibility issues with the new implementation.

We expect the design of encoding/json/v2 to continue to evolve.

Or even earlier in the json/v2 discussion:

However, the module is an experiment and breaking changes are expected to occur based on feedback in this discussion

And of course, the word "experiment" appears in all caps with GOEXPERIMENT=jsonv2.

---

Stepping back, I guess I'm not sure how I feel about new deprecations appearing in a minor release. As @prattmic's analysis showed above, that only would have bought a small amount of time in this case, and only for people who happened to upgrade to the right minor release, so the positive impact might be limited. On the negative side, a perhaps small-ish percentage of people might view that as churn for a deprecation to suddenly appear in a minor release (which might be intermixed with security fixes, for example).

I think @prattmic's #80969 will help a fair amount, as well as generally encouraging people to try out the Go release candidates in advance of a final Go release.

All that said, it's an interesting question to consider.

Finally, I'm just an external contributor, so don't put too much weight on anything I've said.

[dominikh]

(As for Staticcheck, I am aware. That code is based on the actual encoding/json/v2 code, but from before format was removed.)