Document our API

[xymostech]

Someone commented on 21ef03b, noting that it changes the class names that css() generates, and was wondering if that counted as a breaking change. I don't think it is, but I'd like to get some feedback about what we think our API really is, and what we think counts as a breaking change.

This is the way I've been thinking about it, and would propose that we formalize this and document it somewhere (e.g. I've seen babylon document how they follow semver).

The API which we maintain via semver is:

• The types of the inputs that css() and StyleSheet.create (and our other APIs) accept and produce should stay the same. Changing these to something incompatible would be a breaking change. Accepting new inputs would be a minor change.
• The semantics of the generated styles and how they interact with the class names that we generate should stay the same. This means that, if someone uses plain Aphrodite (e.g. with no extensions) and apply single class names to an element, the styles that are applied to that element should not change. Fixing bugs in which styles get applied (like when we reordered styles to make sure that unprefixed styles overruled prefixed styles) would be a bugfix (despite maybe breaking some styles).
• The types and semantics of the selector handler extension API should stay the same. Accepting new types of extensions would be a minor change.
• The "aphrodite/no-important" import.

The API that we do not maintain (i.e. that users should not depend on because it might break in the future) is:

• The text of the class names that are generated via css()
• The text of the CSS that is generated
• Support for "hacky" features such as the hack people use to generate descendant styles by putting spaces in their keys.

How do people feel about this? I think that the most contentious things would be that "fixing bugs in which styles get applied" isn't a breaking change, and that the text that we generate isn't covered.

@drKnoxy @lencioni @kentcdodds

[lencioni]

In general this sounds like a pretty good start to me. I think it probably needs to include a couple of other things, like maybe:

• the async nature of injecting styles
• the testing utility methods for stopping buffering
• the default extensions (animations and fonts)

That's what comes to mind off the top of my head.

[kentcdodds]

Sounds good to me 👍

[merlinstardust]

Would it be possible, and this would certainly be a breaking change, to reverse the !important default and need for a no-important package?

To clarify, I mean, instead have an aphrodite/important package that appends the !important and the base package doesn't append it.

This would still make it easy to integrate with an existing codebase. And if made into a separate package/plugin, then the aphrodite codebase could be made lighter.