Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

proposal: how to specify mechanical code updates after API changes? #18983

Open
LionNatsu opened this issue Feb 7, 2017 · 7 comments

Comments

@LionNatsu
Copy link
Contributor

commented Feb 7, 2017

Go should adopt conventions for packages to explain to potential clients how to update their code in response to API changes in a mechanical way. That is, a package developer should have a way to write down the significant changes of API and compiler and/or tools can apply or fix them.

See also #18130 and #18130 (comment)

@LionNatsu

This comment has been minimized.

Copy link
Contributor Author

commented Feb 7, 2017

My opinion is we can make good use of go fix.

Suppose there is a 'table' for standard packages at "$GOROOT"/RENAME:

$ cat "$GOROOT"/RENAME
# This file could be used for `go fix`
[package]
x/net/context=context
[type]
io.ByteBuffer=bytes.Buffer

$ go fix -rename "$GOROOT"/RENAME [packages]
# -- or --
# use a standard libraries rename table as default
$ go fix -rename [packages]
# -- or --
# include this fix as default
$ go fix [packages]

It's great if godoc can interpret them. Perhaps the 'table' can be written in some format of comment for godoc?

Any thoughts?

@LionNatsu

This comment has been minimized.

Copy link
Contributor Author

commented Feb 7, 2017

cc: @rsc

@davecheney

This comment has been minimized.

Copy link
Contributor

commented Feb 7, 2017

@ScottMansfield

This comment has been minimized.

Copy link

commented Feb 8, 2017

This sounds like something better left to release notes.

I agree this is a very attractive idea, but it's unlikely to be effective in practice. Your conversions will need to cover all possible uses. Also, if you change semantics but not the API that might mean other surrounding code would need to differ and not the specific call to your code.

@kardianos

This comment has been minimized.

Copy link
Contributor

commented Feb 8, 2017

@LionNatsu Typically proposals give a concrete design rather than something like "go should have generics". If you want to float an idea I'd recommend taking it to https://github.com/golang/go/wiki/Questions .

In this case I don't see a concrete proposal, but an idea.

If you'd like to pursue this I would recommend you try to discover methods of doing this, then make it easy for other package maintainers to do it as well. Share it with a few others and revise your design. After you do that feel free to make a concrete proposal with your design.

I'm not trying to dismiss your suggestion; Go has a way to detect API breakages for releases. It has also been suggested in the context of vendoring discussions. Elm has a way to do this too. It may be a good idea. But I havnen't seen a good implementation with a generally useful outcome. That's what this would need to solve before it could proceed.

@kardianos kardianos closed this Feb 8, 2017

@rsc rsc changed the title proposal: to adopt conventions about API changes for package(s) proposal: how to specify mechanical code updates after API changes? Feb 8, 2017

@rsc

This comment has been minimized.

Copy link
Contributor

commented Feb 8, 2017

Reopening. It's true that this is not a concrete, specific proposal, but I do think it's something we should be thinking about and discussing. Much #18130 discussed the problem and solution space before specific solutions, I think that would help here too. This may be open for a long time before we settle on something - it's not on anyone's front burner - but in the long term I believe it will be an important part of how we manage breaking changes in large code bases (along with semantic versioning and fixing other rough spots, like with type aliases).

@rsc rsc reopened this Feb 8, 2017

@rsc rsc added the Proposal label Feb 8, 2017

@rsc rsc added this to the Proposal milestone Feb 8, 2017

@rsc rsc added the Proposal-Hold label Feb 8, 2017

@beoran

This comment has been minimized.

Copy link

commented Oct 13, 2017

A table alone isn't enough in many cases. You will need a Turing complete program. Much like we have the vendor subdir, why not have an fix subdir with an fix package that programatically performs the upgrade? Or, like for go test, have files with a _fix.go suffix? Some kind of standard API needs to be defines, as for go test, but I'll leave that up to the experts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.