Java kernel imlpementation and SVN

Implementers (archive)
1

I believe that the names chosen for branches and tags are totaly confusing. For example the tag Release-0.95 should have be named Release-0.95.0 in order to allow later the existence of a bug-fix tag/release Release-0.95.1. Furthermore the TRUNK should have been already targeted to either 0.95.1 or 1.0.0.

Additionally, the artifacts of the java kernel project (currently openehr-kernel-1.2.5-SNAPSHOT.jar and adl-parser-1.0.2-SNAPSHOT.jar) follow different numbering schemes. I do believe that this is a very confusing situation that makes really difficult the understanfing of the project.

I would like to suggest the following:

  1. Please adopt the same versioning scheme for all the artifacts of the java project. I believe that the current contents of trunk should produce the artifacts openehr-kernel-0.95.1-SNAPSHOT, and adl-parser-0.95.1-SNAPSHOT.

  2. Since project has chosen maven as its build tool, it would be helpful, to document project releases to maven project descriptors

  3. Rename the branch Release-1.0 to something less confusing (for example Release-1.0-work), or delete the branch because it does not contain a release. (It doesn’t even compile) and contribute the code to TRUNK.

  4. Provide more comments when commiting to svn, espesially when branching and merging. It is very hepful to know the origins and the purpose of a branch.

  5. Automate the release process

>My recent experience with Java developers is that it is okay to be
>sloppy and then fix it later.  They use the nice term, "refactor" for
>cleaning up their previous messes

By the way, it was Martin Fowler who introduced the refactoring technique

2

Please send a notification *if* the Branche-names will change names, I have
some scripts running and do not always look at the website.

I do agree with the remarks below, as I said before, it confused me too.

regards
Bert Verhees

3

Haralampos Routis wrote:

Hi Haralampos!

Thanks for the suggestions. Please find my comments below.

I believe that the names chosen for branches and tags are totaly confusing. For example the tag Release-0.95 should have be named Release-0.95.0 in order to allow later the existence of a bug-fix tag/release Release-0.95.1. Furthermore the TRUNK should have been already targeted to either 0.95.1 or 1.0.0.

Additionally, the artifacts of the java kernel project (currently openehr-kernel-1.2.5-SNAPSHOT.jar and adl-parser-1.0.2-SNAPSHOT.jar) follow different numbering schemes. I do believe that this is a very confusing situation that makes really difficult the understanfing of the project.

I would like to suggest the following:

1) Please adopt the same versioning scheme for all the artifacts of the java project. I believe that the current contents of trunk should produce the artifacts openehr-kernel-0.95.1-SNAPSHOT, and adl-parser-0.95.1-SNAPSHOT.

It would be nice to have the same release number for the kernel and parser as the specification they are targeting. But I believe it is not necessary. In particular, the kernel and parser have evolved beyond 1.2 already, it's not possible to go back to the previous numbers.

2) Since project has chosen maven as its build tool, it would be helpful, to document project releases to maven project descriptors

3) Rename the branch Release-1.0 to something less confusing (for example Release-1.0-work), or delete the branch because it does not contain a release. (It doesn't even compile) and contribute the code to TRUNK.

Agreed.

4) Provide more comments when commiting to svn, espesially when branching and merging. It is very hepful to know the origins and the purpose of a branch.

We need to improve the project page to document the work on branches etc.

5) Automate the release process <http://maven.apache.org/guides/mini/guide-releasing.html&gt;

Yes, we too had that wish for long time.

Cheers,
Rong

4

Hi Rong, it always good to read your posts.

Rong Chen rong@acode.se Ýãñáøå:

Haralampos Routis wrote:

Hi Haralampos!

Thanks for the suggestions. Please find my comments below.

I believe that the names chosen for branches and tags are totaly
confusing. For example the tag Release-0.95 should have be named
Release-0.95.0 in order to allow later the existence of a bug-fix
tag/release Release-0.95.1. Furthermore the TRUNK should have been
already targeted to either 0.95.1 or 1.0.0.

Additionally, the artifacts of the java kernel project (currently
openehr-kernel-1.2.5-SNAPSHOT.jar and adl-parser-1.0.2-SNAPSHOT.jar)
follow different numbering schemes. I do believe that this is a very
confusing situation that makes really difficult the understanfing of
the project.

I would like to suggest the following:

  1. Please adopt the same versioning scheme for all the artifacts of
    the java project. I believe that the current contents of trunk should
    produce the artifacts openehr-kernel-0.95.1-SNAPSHOT, and
    adl-parser-0.95.1-SNAPSHOT.
    It would be nice to have the same release number for the kernel and
    parser as the specification they are targeting. But I believe it is not
    necessary. In particular, the kernel and parser have evolved beyond 1.2
    already, it’s not possible to go back to the previous numbers.

Why is not possible? Well known projects with huge and established user community like Apache Struts, have changed in the past their version numbering policy (transition from Struts 1.1 to 1.2.1).

In my opinion, there is a problom. On the one hand the java implementation follows the versioning scheme of the spec on the other hand the artifacts of the java project follow their own numbering scheme.
If really is nessecary that the java project follow its own numbering I suggest that this is reflected to SVN.

For example, the forthcoming next release could be named 2.0.0, documented as implementation of spec-1.0 and containing the artifacts:
openehr-kernel-2.0.0.jar and openehr-adlparser-2.0.0.jar.

5

Haralampos Routis wrote:

Why is not possible? Well known projects with huge and established user community like Apache Struts, have changed in the past their version numbering policy (transition from Struts 1.1 to 1.2.1).

In my opinion, there is a problom. On the one hand the java implementation follows the versioning scheme of the spec on the other hand the artifacts of the java project follow their own numbering scheme.
If really is nessecary that the java project follow its own numbering I suggest that this is reflected to SVN.

For example, the forthcoming next release could be named 2.0.0, documented as implementation of spec-1.0 and containing the artifacts:
openehr-kernel-2.0.0.jar and openehr-adlparser-2.0.0.jar.

obviously this is possible, but the Java user community and openEHR users in general have to consider the confusion factor when the release numbers of software no longer correspond to the release numbers of the specifications. Personally I would rather see them stay together, but recognise that due to parts of the software (i.e. many classes that won't have a counterpart in the specifications) and various functionality, this might not be possible or even desirable. Probably as long as the relationship is clearly documented somewhere it will be fine.

- thomas beale

6

Haralampos Routis wrote:

I believe that the names chosen for branches and tags are totaly confusing. For example the tag Release-0.95 should have be named Release-0.95.0 in order to allow later the existence of a bug-fix tag/release Release-0.95.1. Furthermore the TRUNK should have been already targeted to either 0.95.1 or 1.0.0.

there are things to be corrected in here, I agree. But let's be clear on what we want.

Firstly, if we follow the openEHR CM plan (http://svn.openehr.org/specification/BRANCHES/Release-1.1-candidate/publishing/CM/CM_plan.pdf), we generally create a branch for each major release, when it happens. Then, all following changes to that release - limited to bug fixes (i.e. x.x.N versions) are done on that branch, and merged from there into the trunk (and to other branches representing later releases, as appropriate). THis has the effect that any Release-x.y branch is exactly what it says, plus any more recent bug fixes. But in subversion, I don't believe it is sensible to be creating more and more Release-x.y.n branches for each minor release because this leads to larger and larger checkouts for users (even though it is just symbolic references on the server). Tags can be used, but they also have the same effect on checkout. This is I believe the main design problem of Subversion - the way branches/tags/trunk are just modelled as directories. I don't see any obvious solution for this problem other than not to create too many branches and tags, or else for users never to check out the root URL, but only either TRUNK or else BRANCHES/Release-x.y. This might be a reasonable policy.

If we agreed on that, then I still don't think that you need branches for releases like 1.0.1, since they are "final" - they don't need their own branch. Instead they should be tagged, and build servers pointed to the appropriate tag URLs. Following that logic, you would not bother with separate branches for 1.0, or 1.1. Instead you would create a branch like Release-1 and then do all 1.0.1, 1.1, 1.1.1, 1.1.1, 1.2, etc on that branch, and keep tagging all the way. The assumption here is that there is no lateral branching off level 2 releases, i.e. you could not have competing branches off say 1.2.

The conclusion of this is that we implement 3 -part release numbering as follows:
* with branches corresponding to major release numbers only
* with tags for each minor (level 3) and sub-major (level 2) release
* the trunk is always the latest and fixes are merged into it from release branches; a new release branch is spawned when that release is actually declared, and not before.

I think if we can agree a way to work with Subversion for the group, the advice below can be successfully implemented. However, some discipline is needed.

Further thoughts welcome. Let's get the plan right before changing the repository. If there are some real subversion pros here, let's hear from them.

- thomas beale

7

Thomas Beale Thomas.Beale@OceanInformatics.biz :

Haralampos Routis wrote:

I believe that the names chosen for branches and tags are totaly
confusing. For example the tag Release-0.95 should have be named
Release-0.95.0 in order to allow later the existence of a bug-fix
tag/release Release-0.95.1. Furthermore the TRUNK should have been
already targeted to either 0.95.1 or 1.0.0.
there are things to be corrected in here, I agree. But let’s be clear on
what we want.

Firstly, if we follow the openEHR CM plan
(http://svn.openehr.org/specification/BRANCHES/Release-1.1-candidate/publishing/CM/CM_plan.pdf),
we generally create a branch for each major release, when it happens.
Then, all following changes to that release - limited to bug fixes (i.e.
x.x.N versions) are done on that branch, and merged from there into the
trunk (and to other branches representing later releases, as
appropriate). THis has the effect that any Release-x.y branch is exactly
what it says, plus any more recent bug fixes. But in subversion, I don’t
believe it is sensible to be creating more and more Release-x.y.n
branches for each minor release because this leads to larger and larger
checkouts for users (even though it is just symbolic references on the
server). Tags can be used, but they also have the same effect on
checkout. This is I believe the main design problem of Subversion - the
way branches/tags/trunk are just modelled as directories. I don’t see
any obvious solution for this problem other than not to create too many
branches and tags, or else for users never to check out the root URL,
but only either TRUNK or else BRANCHES/Release-x.y. This might be a
reasonable policy.

I strongly disagree. Firtly, a user does not have to check out all the branches and tags of the project. Usually, an end user checks out the tag that interests her. Furthermore, a developer (of the java kernel checks out) the branches that wants to work with. So, having many branches and tags does not increase the size of the checkouts.

If we agreed on that, then I still don’t think that you need branches
for releases like 1.0.1, since they are “final” - they don’t need their
own branch. Instead they should be tagged, and build servers pointed to
the appropriate tag URLs.Following that logic, you would not bother

with separate branches for 1.0, or 1.1. Instead you would create a
branch like Release-1 and then do all 1.0.1, 1.1, 1.1.1, 1.1.1, 1.2, etc
on that branch, and keep tagging all the way. The assumption here is
that there is no lateral branching off level 2 releases, i.e. you could
not have competing branches off say 1.2.

The conclusion of this is that we implement 3 -part release numbering
as follows:

  • with branches corresponding to major release numbers only
  • with tags for each minor (level 3) and sub-major (level 2) release
  • the trunk is always the latest and fixes are merged into it from
    release branches; a new release branch is spawned when that release is
    actually declared, and not before.

Generally, I agree with this process, except that the fixes (made on a branch) are always applied to trunk. This is not possible for releases that differ significantly. For example, issues reported for 0.95 may not be applied to trunk (Maybe due to the fact that the 1.0 does not contain the same classes).

8

Haralampos Routis wrote:

    The conclusion of this is that we implement 3 -part release numbering
    as follows:
    * with branches corresponding to major release numbers only
    * with tags for each minor (level 3) and sub-major (level 2) release
    * the trunk is always the latest and fixes are merged into it from
    release branches; a new release branch is spawned when that
    release is
    actually declared, and not before.

Generally, I agree with this process, except that the fixes (made on a branch) are always applied to trunk. This is not possible for releases that differ significantly. For example, issues reported for 0.95 may not be applied to trunk (Maybe due to the fact that the 1.0 does not contain the same classes).

agree, of course.

- thomas