go: text/template/parse: backwards incompatible changes
https://golang.org/cl/84480 deliberately makes some breaking API changes saying:
Modifying the text/template/parse package in a backwards incompatible manner is acceptable, given that the package godoc clearly states that it isn’t intended for general use. It’s the equivalent of an internal package, back when internal packages didn’t exist yet.
Additionally, the documentation in text/template/parse says:
Clients should use those packages to construct templates rather than this one, which provides shared internal data structures not intended for general use.
Saying that the package is “not intended for general use” is not the same thing as “this package must not be used by any package other than text/template”. As a result, there exist code that depends on the parse package that are now broken by this change and I don’t believe it is okay to break them.
According to the Go 1 compatibility document:
Go 1 defines two things: first, the specification of the language; and second, the specification of a set of core APIs, the “standard packages” of the Go library.
It isn’t defined what the set of “standard packages” are, but unless an exception is provided, I think it is reasonable to expect that parse is considered one of them (even with the disclaimer and even if this would have been an internal-only package had they existed when the standard library was first created).
About this issue
- Original URL
- State: closed
- Created 6 years ago
- Reactions: 2
- Comments: 15 (12 by maintainers)
May I present option (3): we introduce a CL that both keeps the new functionality and still retains most, if not all compatibility. Unless I’m missing something, this would involve:
AssignNodeback toVariableNode(or creating an alias for that name).PipeNode.DecltoPipeNode.IsDecl.PipeNode.Varsback toPipeNode.Decl.I love the new template feature (I’ve wanted it on many occasions in the past) and I use the template/parse package directly too. Let’s do both. I’ve read through the associated CL a few times, I’m not seeing a good reason why the API was broken in the first place.
sorry, use types from parse in their public apis. Those wouldn’t work right unless the internal/parse library types are aliases and at that point not much has been gained.
This is breaking a handful of targets inside Google. Personally, I don’t think people should be depending on
parsedirectly either. I believe we should either strongly document thatparseis not supported by the compatibility guarantee or we should actually follow Go1 compatibility. Anything in between seems like madness. I don’t have an opinion as to either position we take.I don’t think you can tell people not to depend on the package - many already do. The real question is whether it’s OK to break those that do. We’ve vacillated on that point, but we have done it in the past.
So: Can we document that we reserve the right to break users of this package?
@kardianos yes, that’s what I was suggesting in my first comment, just haven’t found the time to write the CL yet 😃
In an attempt to have our cake and eat it too, we could revert text/template/parse to its 1.10 state, freeze it, duplicate it to text/template/internal/parse, update text/template to use the internal package, and then re-apply the 1.11 changes there. The result is duplicated code, but since the non-internal package is frozen, that shouldn’t hurt too much.