cuelang.org: add a page about the phasing out of list arithmetic

[mvdan]

This page would give users information about our removal of arithmetic on lists from the evaluator. It should include:

• A summary of why it was still supported; it was a legacy feature that hadn't been part of the language spec for years.
• Which CUE version dropped support for this (v0.11.0).
• An example of addition and multiplication of lists, and what the new examples look like with list APIs.
• How to run cue fix to resolve most instances of these in your code.

Then we should link to this page from the evaluator's error message (cc @cuematthew) and we should also link to the page from the release notes announcing this change.

Where should this page go within the website? My intuition is some sort of "Language changes" section under "References", where we would have a collection of these pages, from newest to oldest, so that they can be used as future reference, and be found by googling as well.

[jpluscplusm]

It should include: [...]

I noticed some mention of cuego in a recent CL, and the fact that such tags can't be automatically fixed. What's the messaging we could include on the page for folks using tags and cuego?

Where should this page go within the website? My intuition is some sort of "Language changes" section under "References", where we would have a collection of these pages, from newest to oldest, so that they can be used as future reference, and be found by googling as well.

I think establishing such a "Language changes" subsection inside References would be a useful thing to do, but initially I suggest that we place it inside the /docs/concept/faq/ hierarchy that already exists. The content that can live under .../concept/ has a voice, tone and lead time that's more compatible with getting this done more quickly. We can do some thinking about the more formal References subsection so that's available the next time we want to communicate a kinda-sorta-breaking change like this, and we can backfill it with a modified version of the FAQ that gets written for this issue.

we should link to this page from the evaluator's error message (cc @cuematthew) and we should also link to the page from the release notes announcing this change.

I would suggest choosing a suitable and never-going-to-disappear redirector short link path under https://cuelang.org/s/ for both these purposes. It can link to the FAQ for now, and have its target modified in the future as needed. How about /s/removing-list-arithmetic or /s/list-arithmetic?

[mvdan]

I noticed some mention of cuego in a recent CL, and the fact that such tags can't be automatically fixed. What's the messaging we could include on the page for folks using tags and cuego?

I suggest we don't say anythig about it. We can react if any users turn up. My suspicion is that there are nearly zero users using list arithmetic in cuego tags.

initially I suggest that we place it inside the /docs/concept/faq/ hierarchy that already exists

Sounds good to me. We definitely want to add this quickly and not bikeshed too much.

How about /s/removing-list-arithmetic or /s/list-arithmetic?

That sounds like a good idea as well. How about something that hints a bit more towards a breaking change in a particular version, like /s/v0.11-list-arithmetic?

Go have started doing something similar (and I think this is where Paul and I got the idea from): https://go-review.googlesource.com/c/go/+/497715

They have gone with /e/CamelCaseName for various types of typechecking errors. I think it makes sense to use a different short prefix too, like /e/, for the sake of not mixing the namespace - so I would suggest /e/v0.11-list-arithmetic. I don't think we need to copy the CamelCasing; I personally don't think it fits very well with readable URLs.

[jpluscplusm]

I've opened hofstadter-io/cuetorials.com#83 to remove mention of them from the obvious location on cuetorials.com. I've not exhaustively checked through the rest of the site looking for other uses.

[jpluscplusm]

I've started a page containing these questions in https://cuelang.org/cl/1200357. Let me know if you feel there are others that need to be included, or more useful wording for these:

• What’s being removed, and from where?
• Why were list arithmetic operators supported until now? << I'm not sure about this one. Is it even needed?
• What’s the replacement for list arithmetic operators?
• Which version of CUE removes list arithmetic operators?
• Am I affected?
• I am affected! How can I fix my CUE?

[cuematthew]

FWIW, that CL reads nicely to me so far.

[jpluscplusm]

Closed via cue-lang/cuelang.org@1db4043