Documentation of old and new APIs

[akinomyoga]

We have released the new API for the completion settings in 2.12 (after discussions in #539 and related Issues and PRs).

Now, new external completions in the wild have started to use the new API. However, the bash-completion package that they are going to depend on might not be as up-to-date as 2.12. As we have discussed in #537 (comment), we actually think that the external completions can still depend on the previous API for now. At least, the old API would not go away until all the bash-complete packages in major distributions are updated to 2.12 or above, and we predict that it will take about a decade. After that, we can recommend the external completions to use the new API so that they work everywhere with a back-completion package. Even then, we do not have a plan to remove the older API.

However, our stance is not so obvious to external people, so we sometimes need to inform them about it, e.g. as in #1317 (comment).

In addition, there seems to be confusion about the relationship with an even older API of v1.0 (which we still provide for backward compatibility) as in #1220 where the OP seems to consider the newer API as the one for bash-completion v2. Another confusion is that the relationship between the functions of different API sets, such as have (from the oldest one), _have (until v2.11), and _comp_have (added in v2.12), as in libsixel/libsixel#89.

I think it would be useful to document these matters in one place.

Suggestion: API version numbering

I suggest giving a number to the older and newer API sets. Naively, we could call an API set with the version number of bash-completion itself, such as "v2.11" vs "v2.12". However, the current situation, where we implement "v2.12" but still recommend external completions based on bash-completion v2.12 to use "v2.11", would be confusing.

Since the new API would be backward-incompatible with the older API, I think it would make sense to call the newer API "API v3" (as I originally used this in #1220 (comment) as a temporary API name). When the bash-completion packages in major distributions are entirely replaced with 2.12 or above, we can also update the version of bash-completion itself to "v3.0". This is my idea.

Then, the older API used until v2.11 can be called "API v2". An even older one can be called "API v1".

Suggestion: Examples of completion settings based on API v2

Another issue is that we do not have completion settings based on API v2 in the latest version of bash-completion. This means that external completion writers don't find official references for writing completions based on API v2, although we still recommend that external completion writers use API v2 if they want it to work everywhere.

For comparison, we may also describe the completion settings based on API v3. Since some completion settings still seem to rely on API v1, we may also show an example with API v1 so that the completion writer can migrate to API v2 or v3.

Suggestion: Migration guide and comparison table

It would also be useful to describe how to migrate from v1 to v2 and v2 to v3. We may provide a table of corresponding API names between different completion settings, to illuminate the relationship between e.g. have, _have, and _comp_have.

[Kreijstal]

libsixel was archived for no reason, so forking it here https://github.com/Kreijstal/libsixel in case anyone wants to still write issues/prs

[scop]

Makes sense to me. I think it could be a source of confusion to have API v3 implemented in >= 2.12, but I don't know if there's an entirely confusion free alternative available. Docs would help.