Let's say there's a successful open source application (written in PHP if it matters), which provides its users with multiple ways to extend it (think about something like Drupal or Wordpress, lots of custom plugins, etc.). Now let's say unfortunately there's no formal definition what constitutes the public API for this application, and we want to define such a public API, so that we could a) control application development and refactoring and know we don't screw up the extensions with the next version and b) give extenders some idea what they can safely use and what they better not use. So the question is - how is it best to approach this and what should be there? For example, some specific questions:
- Should all classes be part of public API or should we mark those are public or mark those that aren't?
- Should protected methods be part of the API (if somebody creates derived custom class, they will be relying on it) and if so - should we be explicitly marking those that we don't want others to use, or those we're allowing to use?
- Should public properties be part of the API too? How about protected ones?
- If we want to make change/refactoring which can't be backwards-compatible (e.g. old API was too buggy or doesn't really fit in the app anymore), how we best approach it?
- If we want to remove some class/method completely, what should be the process? I imagine we want to make it deprecated first, and then remove in later versions, but for example should we give some warnings when deprecated, but still existing functionality is called? The problem here is we can't warn to aggressively as it may break the application, but if we're not agressive people would ignore the deprecated mark until we remove the old API piece and then they'd get major breakage.
Any other advice is welcome too, and references for good papers/examples/etc. on the topic.