-
Notifications
You must be signed in to change notification settings - Fork 9
Backwards compatibility and internal API policy
This document defines the Backwards compatibility (BC) promise, i.e., which parts of the Composer Stager codebase are considered stable and reliable APIs, and which parts client code should not rely on.
All classes in the Composer Stager codebase are designated either public or internal:
- Public APIs
- Public APIs are considered stable and reliable, and client code can safely depend them. They will not be changed or removed between major releases except in critical cases such as a security issue.
- Internal APIs
- Client code should avoid calling internal APIs because they might be or removed at any time without notice.
All classes in the src directory are tagged accordingly. Everything else is implicitly considered internal.
The source code in src/API constitutes the public API, including interfaces, traits, and exceptions. The API layer includes no concrete implementations. Services should be injected by their interfaces using an autoloader. See Configuring services.
All other source code, i.e., in src/Internal, is considered internal. This includes, by extension, dependencies and class hierarchies. Most notably, that means that preconditions may be added or changed at any time. As long as you use a service container with autowiring enabled, such changes will be automatically applied without interruption to you. As long as you depend on interfaces, you can still replace concrete implementations and decorate preconditions.
The various "UI" strings--for labels, descriptions, and messages--are subject to the BC promise for the purpose of translatability. Nevertheless, many of them are dynamic, and string comparison should never be used on them for conditional logic.