I've heard more than a few people express some confusion about what is meant by "public API", especially since I have lauded Rails for having an excellent user-facing API. How does that jive with the agenda of creating a defined, documented API?

To clarify, I am applauding Rails for having created a developer interface to the framework that is pleasant to use. A lot of code that is created using the Rails DSL is immensely understandable, even to relatively new users, because of a passionate focus on making it so.

When I talk about "public API" I mean something much more boring and technical. In particular, I mean dividing up the parts of the Rails internals that are meant to be used, documenting them as public, and writing tests that are specifically marked as public and cannot be changed without a darn good reason. At present, while the public-facing API is relatively stable, there is no infrastructure around making it so.

But perhaps more important is the idea of doing the same for plugin developers that Rails has already done for end-users, by forming known, defined, and tested mechanisms for adding or modifying Rails behavior. In the same was as for public-facing functionality, we should document the methods that are intended to be used by plugin developers, create hooks where appropriate, and write tests to ensure that these contracts with plugin developers remain so.

Once this is done, and the private functionality of Rails is well cordoned off from the parts that are intended for public or plugin use, the Rails team will have significantly more latitude to keep the internals of the framework from getting crufty too quickly. We found this approach to be quite useful in Merb, and the plan is to do the same for Rails.

Of course, it can hardly be said that by creating a public/plugin API we will have completely removed the need for anyone to ever monkey-patch Rails internals directly. However, it will be more clear which modifications are likely to survive from version to version, and which modifications will require constant vigilance (and should probably be the subject of a conversation with the Rails core team itself to determine whether a more explicit hook could be added).

In short, when I say "public API", I mean documentation, testing and commitment.