Simon, anonymous wrote : Every API needs a contract, a set of documented rules that defines a model and how the model is affected. As far as I can see, the kind of documentation you're looking for won't happen in this project until either: - there's some immediate, undeniable business imperative for JBoss, like a big customer demanding it. I am hopeful - it's pretty scary to be basing commercial product on something whose behavior I know well only where I've dug hard into the code. Presumably some major customer will have the same misgivings. or - folks come up with a clean way for it to be incrementally contributed to by users. Since the doc at the level you're looking for is classically in the javadoc, that's hard, because it requires either committer access or for someone to take the time to merge comments. Ensuring accuracy from folks who aren't the primary authors will be hard, too. They might consider contributing unit tests, as well, which significantly raises the effort level required. I don't know if anyone would be interested. Also, as far as I know, there's currently no formal notion of "the JBPM interface" - i.e., a restricted set of classes/methods that are intended for use outside the jar. Any contract/specification work would need to start with that definition of what is intended to be "truly public". I don't have any idea whether the current committers would find any value in any of this. So far, no sign of it. On the other hand... given where we are... for myself (and apparently for Ronald ;-)), I'd certainly appreciate it if you'd prune your technical queries by doing a bit more legwork. In the current case, the fact that a JbpmContext scopes transactions is documented in both user guide and javadocs, and could have been surmised by anyone with your experience - it's a common pattern. -Ed Staub View the original post : http://www.jboss.com/index.html?module=bb&op=viewtopic&p=4046124#... Reply to the post : http://www.jboss.com/index.html?module=bb&op=posting&mode=reply&a...