Documentation proposal
Overall I propose we have the following documents:
-
Hibernate Manual- The main reference manual. The intention is to overhaul the reference manual and re-integrate the pertinent information from the dev-guide. We’d need to determine whether a separate dev-guide still makes sense. The intention for the dev-guide was always to describe SPI/integration concerns. However some "user information" definitely made its way in there. -
Hibernate Domain Model Mapping- Discussion of annotations and hbm.xml mapping of the domain model. This is such a massive topic that it is already split into multiple chapters in the existing manual. -
Dev Guide- if we decide we wish to keep that doc separate. The name should be more like "Hibernate Integrations Guide".
Order is still tbd
Mainly the same topic as content/persistent_classes.xml from the manual, but augmented with information from other
sources such as Anthony’s discussion of equals() and hashCode() (https://developer.jboss.org/wiki/EqualsandHashCode), etc
The intent here is to discuss the purely Java aspects of defining a domain model. As mentioned above, the plan is a separate doc for decribing how to map a domain model.
Discuss Session/EntityManager as a persistence context in regards to state (managed, transient, detached) transitions.
chapters/pc/Persistence_Context.xml in the dev-guide is a great start. The information from the content/readonly.xml
manual chapter should also be folded into this discussion imo.
Discuss access to the database. Database_Access.xml from the dev-guide and parts of the updated content/bootstrap.xml
chapter from the manual combined make a great start.
Discuss transaction, concurrency and optimistic/pessimistic locking. Great start in a combination of
-
updated
content/bootstrap.xmlchapter from the manual -
chapters/transactions/Transactions.xmlin the dev-guide -
Locking.xmlin the dev-guide
I really like the discussion I started in the dev-guide chapter chapters/fetching/Fetching.xml
First we need to decide what all to discuss here as that phrase has so many connotations. Do we cover
-
JDBC batch updates?
-
StatelessSession?
-
Session w/ incremental flushing?
-
Java EE batching?
Any/all of the above? Others?
The updated content/bootstrap.xml chapter from the manual has a good grouping of the settings that effect JDBC batch updates.
Again the updated content/bootstrap.xml chapter from the manual has a good grouping of the settings that control
caching. Caching.xml from the dev-guide is a good structure I think.
Discuss Statistics and SessionEventListener. See the updated content/bootstrap.xml chapter from the manual, as well
as the content/performance.xml chapter from the manual
Discuss database portability, environment portability and even JPA provider portability.
The discussion in src/main/docbook/devguide/en-US/Data_Categorizations.xml is a great start to this document I think.
In addition to the various chapters on mapping in the manual, there are lots of great external sources of information we could pull from for this document.