Document high-level model building concepts

[ajcvickers]

Such as:

• Fluent over Attribute over Convention precedence for mapping
• Last-one-wins in Code First

[AndriySvyryd]

• If a metadata property/navigation name matches a CLR member it must be using it (can't be shadow).
• IModel vs IMutableModel vs IConventionModel vs ModelBuilder vs IConventionModelBuilder
• Show how to print out the Debug view of the model before and after model validation.
• ConventionBuilders throwing for invalid configuration and returning null for overriden configuration
• Metadata API have no side effects (apart from conventions), ConventionBuilders will try to make the adjustments to make the configuration valid, but will offload as much as possible to the conventions

[AndriySvyryd]

Why should we use conventions instead of hardcoding the configuration in builders

Pros

• Composability. The logic contained in a convention doesn't directly depend on logic in other conventions. This makes them easier to test and resilient to code churn.
• Extensibility. Conventions can be added, removed, replaced and reordered by providers and (soon) by users
• Efficiency. By separating the configuration change event from the code that processes it we can avoid unnecessary calls. (E,g, if a property is removed before the added event is processed then neither event needs to be processed).
• Maintainability. Having the code separated into files by functionality makes it easier to find and understand than having it spread out through builders that are separated hierarchically.

Cons

• They add overhead and will be slower in many cases.
• Authoring them requires better understanding of how model building works