Misleading passage in deprecation policy?

[wshanks]

DEPRECATION.md states

Beware that users will often be using functions, classes and methods that we, the Qiskit developers, may consider internal or not widely used. Do not make assumptions that "this is buried, so nobody will be using it"; if it is public, it is subject to the policy. The only exceptions here are functions and modules that are explicitly internal, i.e. those whose names begin with a leading underscore (_).

While I think the "if it is public it is subject to the policy" part saves the passage from being wrong, I think the passage reads oddly. It predates the "What is the public interface?" section and was written, I think, when "public" meant "anything not starting with a _." I think this would be more in keeping with the current policy:

Beware that users will often be using functions, classes and methods that we, the Qiskit developers, may consider unused. Do not make assumptions that "this is buried, so nobody will be using it"; if it is public, it is subject to the policy.

I removed "internal" because if Qiskit developers consider something internal it would not be documented and thus would not be public and subject to the policy. Likewise, I removed the last sentence since I think it corresponds to the older definition of public.

I was puzzling over this section because qiskit-ibm-runtime copied this file before the "What is the public interface?" addition, so I was trying to decide if I could a function not starting with a _ there or not.

[jakelishman]

I think I wrote that first paragraph you quoted some time before we properly defined the public interface to be "documented in the public API documentation" (or whatever precise form we actually used). So the first paragraph you quoted is most likely out-of-date.