Has there been any work on a coding standards document yet?
I'm currently working on fixing documentation on this project, and it might be a good time to define a standard.
I've started compiling a few recommendations based on various feedbacks I've got in my pull requests, and I can post them here.
Please let me know if there have been previous attempts so far!

Benjamin Morel Guilherme Blanco may have a CS ruleset, but it's not ready yet. Perfect timing btw, we really need to automate this to avoid having all these useless CS fix comments in pull requests

Ok, I'll post my document here once ready, and Guilherme Blanco will be able to compare it with his ruleset!

Here is a first draft: https://gist.github.com/4676670

Please comment!

Guilherme Blanco, if you don't have time to compare your ruleset with my draft, maybe you could publish your current ruleset so that others can have a look?

i just found a possible BC issue with this.

EntityRepository is allowed to be extended by us, it has several variables that are underscore prefixed. How to proceed in this case?

I know but its not really a problem I think. We should just decide whether we make them private in the first place and provide getters instead (which would have avoided this problem in the first place).

Leaving the prefixes on the repository class only is also an option... but I dont think thats necessary.

can we commit getters for Beta 1 then? We could give everyone a period until Beta 2 to fix their code and then make the change.

EntityRepository is the only class that is meant to be userland extendable to my knowledge, so this should be the only problem to adress

Yes, you can add getters and commit right away if you want. Plus adding a note on the upgrade document that direct access of these properties is deprecated.

Persisters will be also extensible some day in userland but they need more polish for that, I've already started with it

Is this still planned? Searching the code base finds this is not being implemented. It would be a good idea to implement the change sooner than later if it will be done at all. Also, +1 for the change. It makes complete sense.

Apparently it's also incompatible with several other tag as well.

I thought it made sense to try the following and see if the @InheritanceType and @Discriminator___ tags would apply to the children classes:

/**
 * @MappedSuperclass
 * @InheritanceType("SINGLE_TABLE")
 * @DiscriminatorColumn(name="type", type="string")
 * @DiscriminatorMap({"User" = "User", "Group" = "Group"})
 */
abstract class Principal

But apparently this flags D2 to treat it as an Entity anyway, resulting in the following error:

PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'sentact5.principal'

I updated the documentation, the question is if we should check for the mapped superclass attribute and throw exceptions if other entity level annotations are specified.

A mapped superclass has not many restrictions and these are mentioned in the docs (i.e. only unidirectional associations), what David mentions above should work, if it doesnt its a bug, I think DDC-511 looks like that same issue.

David,

@"Is this defined on the superclass or on the children classes?"

It doesnt matter. A @MappedSuperclass can be anywhere in an inheritance hierarchy and it always does the same thing, inherit its mapping information to subclasses (but its not itself an entity). The docs say:

Mapped superclasses, just as regular, non-mapped classes, can appear in the middle of an otherwise mapped inheritance hierarchy (through Single Table Inheritance or Class Table Inheritance).

as well as

Entities support inheritance, polymorphic associations, and polymorphic queries. Both abstract and concrete classes can be entities. Entities may extend non-entity classes as well as entity classes, and non-entity classes may extend entity classes.

So entities, mapped superclasses and plain non-mapped classes can appear mixed in an inheritance hierarchy. Nevertheless all the classes in a hierarchy that are entities must use 1 inheritance strategy, you can not mix inheritance mapping strategies in a single class hierarchy.

@"If it's defined on the child classes, does it take parameters? The name of the super class?"

No, it doesnt. The docs dont mention any parameters either which is correct.

@"It was not at all apparent to me that it was mutually exclusive with the @Entity tag"

OK, that needs to be made clearer in the docs then.