Public interface and backward compatibility #537
Replies: 6 comments 30 replies
-
I share the concern, this is kind of a problematic area. Previously there has been no notion of a public interface, and as we do encourage upstream completions to use our helpers, it's fair for upstreams to have assumed that it's ok to use anything we provide. I don't have a good answer for what would make something public and something not. Pretty much the only reason I wouldn't like everything to be public is the ability to make incompatible changes. I guess the best approach I can give off the cuff would be to not make those at all, but to introduce incompatibilities in new functions. That'll obviously build up cruft over time. We can deprecate things and add warnings to fight that and eventually just remove old stuff, but that's something we haven't been too good at. Added #542 related to that. On another semi-related note, I've started applying |
Beta Was this translation helpful? Give feedback.
-
Functions returning results by setting local variablesLet me create a separate thread for returning results through variables. The original discussion started around #537 (reply in thread). I summarize here my current understanding of the direction in the original discussion.
For the other functions, we generally recommend using a common fixed name,
edit: We also have "exporter functions", namely, the functions that write variables on the specified variable name. The related discussion on the local variable names used in exporter functions is found in #539 (comment). |
Beta Was this translation helpful? Give feedback.
-
Exceptions to
|
Beta Was this translation helpful? Give feedback.
-
Existing functions that return results through
|
Beta Was this translation helpful? Give feedback.
-
Switching
|
Beta Was this translation helpful? Give feedback.
-
Hi! While pondering about upstreaming the dpkg support, I ended up having to also ponder about the API bash-completion provides, and whether that can be used by external projects. First of all, I think the API cleanup, namespacing and general rework that has been going on is great. One problem though is that I'm not sure external projects can rely on being able to use those, because usually this is something that you install on the system, but do not want to have a hard dependency on, and that means it's hard to express versioned relationships (I mean for something like dpkg one could declare a versioned Breaks relationship to force a higher bash-completion version, but…). This also brings the question that I think you have touched about when to obsolete/remove APIs, and for external projects that would seem tricky. And finally there's also the tension between shipping the completion with bash-completion and getting all this global code improvements and being able to use the latest and greatest APIs, but having a slow release cycle disconnected from the changes in the upstream projects, or having the completion upstream in sync with the commands being completed, but not being able to benefit from these code cleanups and API improvements. I'm tending towards the latter, but that also means that if every single project adopted the completion support upstream, as I think is the preference here, that would mean much of the great APIs provided might then not be usable by those external parties, which also seems like a pity. :/ |
Beta Was this translation helpful? Give feedback.
-
We are recommending that the completion for each specific command is preferred to be maintained along with the command itself.
bash_completion
provides helper functions which can be used from such external completions.However, one of the concerns that the writers of the external completion might have is the backward compatibility of helper functions in
bash_completion
.Question: Is there any borderline between public interface (i.e., stable helper functions which can be used from external completions) or private interface (i.e., the helper functions whose names might be changed or whose detailed behavior might be changed in the future without notice). Or are all the functions appearing in the main script
bash_completion
considered public interface?If everything is considered public interface, I think it is harder to make changes to
bash_completion
keeping the backward compatibility. By designating public interface which can be used from external completions, I think we can more safely change/update/reorganize the implementation ofbash_completion
, etc., and also the external completion writers can easily look up useful helper functions from a shorter list and don't have to care about the version differences ofbash_completion
too much.Beta Was this translation helpful? Give feedback.
All reactions