text/template/parse: backwards incompatible changes

[dsnet]

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).

\cc @mvdan @robpike @cybrcodr @bradfitz

[ghost]

Some related discussion is over here: #25357

[dsnet]

For some background, the last time parse was changed in an incompatible was for Go1.1. See https://golang.org/cl/6586074 and https://golang.org/cl/6576058. Thus, the API has been mostly stable for the past 6 years.

[robpike]

I remain happy not to have this change at all, but seem to be in the minority. People want the feature.

[ghost]

@dsnet What action do you propose? Drop the change? Re-rename the renamed public types/variables/etc back (is that enough?)?

[mvdan]

I would have originally thought that breaking the parse package was not possible, but since Rob approved the change and gave a reason in favor of doing so, I didn't give it more thought.

I can have a look at undoing part of the changes to the parse package, so that Go1 compatibility is kept without reverting the entire CL and feature. That could be a short-term solution, while #25357 is more of a long-term one.

As for the text/template feature - I imagine that it's not the point of this issue to undo the entire CL. There was demand for it and the proposal was accepted. But if someone wants to make a point to also revert the feature before 1.11 is out, now is the time to speak up :)

[dsnet]

This is breaking a handful of targets inside Google. Personally, I don't think people should be depending on parse directly either. I believe we should either strongly document that parse is 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.

[mvdan]

@dsnet I agree, and I too find either option acceptable. @robpike @rsc @rogpeppe any thoughts?

[robpike]

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?

[josharian]

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.

[jimmyfrasche]

{text,html}/template use types from parse

[josharian]

internal/template/parse, then. Ugly, true.

[jimmyfrasche]

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.

[kardianos]

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:

• Rename AssignNode back to VariableNode (or creating an alias for that name).
• Rename PipeNode.Decl to PipeNode.IsDecl.
• Rename PipeNode.Vars back to PipeNode.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.

[mvdan]

@kardianos yes, that's what I was suggesting in my first comment, just haven't found the time to write the CL yet :)

[gopherbot]

Change https://golang.org/cl/120355 mentions this issue: text/template/parse: do not break API