We've got a substantial list going for Seam 3:
While working on these, I couldn't help but to think that perhaps we should have some foundation guidelines at JBoss Community. That way, each project can say "we extend those guidelines in the follow ways" rather than having to start over every time. It would also make my IDE setup simpler since I wouldn't have to keep importing formatting profiles for every project.
So while I agree JBoss Testing would be a good umbrella, maybe we need to go higher. Perhaps even version them, so we say "JBoss Development Guidelines 1.0".
The only thing that concerns me about going any higher than "JBoss Testing" is that it'll become increasingly difficult to get concensus about what constitutes "good form" from the variety of personalities throughout the .org community. In many senses it's a great thing that each project gets to govern its own land.
For instance in EJB3 we set steadfast rules regarding backwards compatibility and componentization that would infuriate the lot here. But because we have different requirements, they become necessary in that arena.
Got it. That does make sense because I know these things can become ideology wars. I can only imagine what a response might be on thecore. That's why I'm suggesting "profiles". We can create these profiles but share them for central reference. On the one hand, we could have a "JBoss Testing" profile, but I think that makes projects which don't consider themselves testing hesitant to adopt them.
So perhaps was can just use an arbitrary name, like from the military alphabet: "alpha" "bravo" or whatever. I just think that makes more sense then saying "Weld" or "Seam" profile since it is really something people just latch on to. It's a common set of conventions that we all share.
I suggest: Tango
And we should version it, so that we can track when it changes (so people know to check it out again).
Unless you think I'm completely insane, I'll create a Tango 1.0 development guidelines page and say "we follow that".
Projects like Seam and Weld can of course extend it for specific things, like how to define interceptors or something. But at least those are only the parts that differ from Tango, rather than restating it all from scratch.
All of our code, especially SPI or API classes must have javadoc which explains in detail the following things:
1) How the module is supposed to be used (and how it is actually used if known)
2) The intended behaviour, and any aspect of it that is known to be broken or a hack (so that someone can differentiate between a design problem and just an unimplemented section that needs to be fixed)
3) Critical preconditions (e.g. "this class expects that the same vfs handle instance be reused during a redeploy")
4) Thread-access design (e.g. "this class is thread-safe and can be accessed from multiple threads", "this class is not thread-safe, and all callers must use a shared lock to access", "this class is intended to have an instance-per-thread")