[hibernate-dev] Hibernate Commons project

[Guillaume Smet]

On Tue, Jan 31, 2017 at 11:34 AM, Gunnar Morling <gunnar at hibernate.org>
wrote:

> == Repo organization ==
>
> I would prefer to have the AsciiDoc style, shared testing utilities
> and other utilities in separate repos, not a shared one. To me, a repo
> represents a coherent unit of "things" with its own lifecycle. Updates
> to the style should not mandate an update of the version of the
> testing and other utilities, so they should be in their own repo. This
> should also make it easier in terms of licenses (no need for
> relicensing).
>

Yeah, that was my first intention but I got outnumbered and to be honest I
don't really care as long as they are purely internal projects. I'll let
Yoann and Sanne explain their point of view as they will do that better
than me (IIRC, it was mostly about the maintenance cost but I'm not sure it
makes a difference if the lifecycles are completely different).

Anyway, it does not solve the license issue. As per our discussion last
week, if we have some general utilities to share between the NoORM projects
for instance, we would probably like to copy the sources of the utilities
to avoid conflicting dependencies when depending on 2 of the projects
(probably using
https://maven.apache.org/plugins/maven-dependency-plugin/examples/using-dependencies-sources.html).
In this case, I think we would need to dual license (ASL 2 + LGPL) the
utilities as the sources will be distributed with the rest of the projects.

So, if I try to sum it up:

== GroupId ==

2 proposals:
- org.hibernate.common (the same as hibernate-commons-annotations)
- org.hibernate.internal

(let's drop my initial org.hibernate.commons proposal, it's too confusing
with org.hibernate.common)

== The license ==

The license: probably better to dual license everything under the ASL2 and
the LGPL - especially if we start to share utilities.

Will check with Emmanuel when he's back.

== The AsciiDoctor theme ==

We mostly agree that it's probably better to converge on a similar layout.

Steve seems to be strongly attached to the Hibernate theme.

I personally don't like it and think it would be more painful to maintain
in the long term as it overrides more things. Sanne was also more convinced
by the white banner.

If I sum up the differences between the 2 themes (
http://docs.jboss.org/hibernate/stable/orm/userguide/html_single/Hibernate_User_Guide.html
vs http://docs.jboss.org/hibernate/beta/html_single/):
- black banner vs white banner
- original Docbook icons vs font based icons (Font Awesome)
- dark blue titles vs standard red ones
- admonitions are totally different (compare
http://docs.jboss.org/hibernate/stable/orm/userguide/html_single/Hibernate_User_Guide.html#naming
and the end of this paragraph
http://docs.jboss.org/hibernate/beta/html_single/#search-batchindexing-threadsandconnections
)
- a lots of fonts loaded in the ORM doc but I must admit that I think most
are useless:
http://docs.jboss.org/hibernate/stable/orm/userguide/html_single/css/hibernate-fonts.css
so we could probably clean this up
- more overrides (compare
http://docs.jboss.org/hibernate/stable/orm/userguide/html_single/css/hibernate-layout.css
vs http://docs.jboss.org/hibernate/beta/html_single/css/hibernate.css) so
more maintenance if the HTML output of AsciiDoctor is changed - note that
I'm new to AsciiDoctor so I don't know how stable the HTML output is

The ORM output might have been better than the default AsciiDoctor output
at the time it was made, but as of now I really think the current
AsciiDoctor output is more pleasant to read and more modern. And we would
benefit from future improvements for free.

-- 
Guillaume