This page was moved to https://cwiki.apache.org/confluence/display/CAUSEWAY/Make releases easier and more frequent
Click in the link above if you are not automatically redirected in 10 seconds.


Discussion

In the mailing lists we've been discussing how to restructure the codebase to make releases easier to do, see isis-users thread and isis-dev thread.

Interim Conclusions (as of 7pm, 4 Dec 12):

  • yes, to idea of independent, more granular releases (this means that separate modules so don't share common parent, ie are separate artifacts)
  • refactor the groupId/artifactId's to aid understandability:
    • all artifactIds have an 'isis-' prefix so that, when assembled together in a single directory (eg WEB-INF/lib), they are easily identifiable as being Isis'.
    • all artifactids also specify the component type, otherwise would be confusion between isis-sql.jar: is it an objectstore, or is it a security impl, or what?
    • prefer that artifactIds read well, ie "isis-nosql-objectstore" rather than "isis-objectstore-nosql"
  • consolidate artifacts so clear distinction between core vs non-core where makes sense
  • go with a small set of groupIds, broadly reflecting nature of component
  • don't move separate modules into their own git repos?
  • don't retire modules just yet (except perhaps the old monitoring module)

Still being debated/to be discussed:

  • is it ok for the default progmodel to be bundled with core?
    *8 assuming it is, should its groupId be core, or "progmodel"?
  • is it ok for the default (identity) bytecode to be bundled with core?
    • assuming it is, should its groupId be core, or "progmodel"?
  • are we happy to rename oai.core:isis-core to oai.core:isis-metamodel ?
  • use of isis-parent as a parent (non aggregating) pom defining release management configuration for all releaseable artifacts

Proposed GroupIds

The table at the end of this page summarises proposed refactorings for all the current Isis artifacts. But to cut to the chase, we would end up with the following groupIds:

org.apache.isis.archetype
org.apache.isis.core
org.apache.isis.objectstore
org.apache.isis.viewer
org.apache.isis.security      
org.apache.isis.profilestore  
org.apache.isis.progmodel     

Proposed Directory Structure

The proposed directory structure to hold the Isis artifacts is shown below.

Some notes:

  • Note: a "/*" suffix indicates additional sub-directories.
  • I've deliberately shown this alphabetically so we can easily what this means in practical terms.
  • I've added a new isis-parent directory to hold the parent pom.xml for all releasable modules (ie archetype/, core, and component/)
  • I've renamed oai.core:core to oai.core:metamodel
  • Have removed 'deployment' and 'development' subdirs from core (talking further with Jeroen, decided no longer much value to having this)
core/
  applib                 
  bytecode-cglib
  bytecode-javassist
  metamodel              # most of core; basically the metamodel, facet factories, default progmodel, and a runtime API
  runtime                # the default runtime impl (IsisContext service locator, default impls of components, objectstore API)
  webserver
  integtestsupport       # for end-users when writing their apps, also used internally for tck end-to-end tests
  tck/*
  unittestsupport        # core's testsupport module, mostly for our own unit testing purposes
component/                # all components are released separately from core
  objectstore/
    inmemory
    jdo/*
    nosql/*
    sql/*
    xml/*
  profilestore/
    inmemory  
    sql
    xml
  progmodel/
    groovy
    wrapper
  security/
    noop
    file
    ldap
    sql
  viewer/
    bdd/*
    dnd
    html
    junit
    restfulobjects/*
    scimpi/*
    wicket/*
example/                   # various examples, not released, some used to reverse engineer archetypes.  Very good candidate to move into a separate "isis-examples" repo.
  application/
  archetype/
    dnd-xml
    dnd-junit-bdd
    scimpi-nosql
    wicket-restful-jdo
  domain-entity/
  domain-service/
isis-parent/               # parent POM for all releasable components                    
retired/
  monitoring
site-skin/
tool/
  maven-plugin
  structure101             # not released, .java.hsp project files used to create documentation

As noted above, all of the pom.xml's for each of the components are separately releaseable. This is probably through a new oai:isis-parent parent (non aggregating) POM.

We might decide at a later date to move each of these top-level directories into their own git repo. If we do that, will probably want to use main artifactId, eg: isis-dnd-viewer.git, isis-jdo-objectstore.git etc.

Refactoring: Proposed Module Moves/Renames/Consolidations etc.

The table below summarises proposed refactorings for all the current Isis artifacts.

Type column:

  • C = core, parented by "org.apache.isis:isis-parent" (as currently)
  • L = rolled up into parent with other modules, see Notes column for further details
  • A = alternate implementation, not parented by org.apache.isis:isis (instead would define its own parent), thus separately releasable. Might move to own git repo
  • E = edition, ie an archetype, not parented by org.apache.isis:isis (instead would define its own parent), thus separately releasable. Might move to own git repo
  • X = excluded, parented by "org.apache.isis:isis" but not released (excluded through use of Maven profile). Might one day be promoted to being an alternate implementation.
  • R = retired
  • D = deleted

In the table below, I've removed the proposed location column, since this information is now shown above.

current

current

proposed

proposed

 

 

groupId

artifactId

groupId

artifactId

Notes

o.a.i

isis

o.a.i

isis-parent

Release configuration moved to new pom intended to be parent of all releaseable artifacts

o.a.i

isis

o.a.i.core

isis

Acts as aggregator of isis core modules

o.a.i

applib

o.a.i.core

isis-applib

 

o.a.i

isis.core

o.a.i.core

isis-metamodel

Source from submodules rolls up to this parent (packaging=jar; not packaging=pom)

o.a.i.core

commons

Rolled up into oai.core:isis-metamodel

o.a.i.core

metamodel

Rolled up into oai.core:isis-metamodel

o.a.i.core

progmodel

Rolled up into oai.core:isis-metamodel

o.a.i.core

testsupport

o.a.i.core

isis-unittestsupport

Not rolled up; because intended to be referenced with scope=test; renamed to distinguish from integtestsupport

o.a.i.core

webapp

Rolled up into oai.core:isis-metamodel

o.a.i

isis.runtimes

Delete module; due to flattening

o.a.i.runtimes

dflt

o.a.i.core

isis-runtime

Source from submodules rolls up to this parent (packaging=jar; not packaging=pom)

o.a.i.runtimes.dflt

runtime

Rolled up into oai.core:isis-runtime

o.a.i.runtimes.dflt

testsupport

o.a.i.core

isis-integtestsupport

Utilities for end-users to write integration tests using Isis (cf Arquillian); also used by tck tests internally

o.a.i.runtimes.dflt

webapp

Rolled up into oai.core:isis-runtime

o.a.i.runtimes.dflt

webserver

o.a.i.core

isis-webserver

To bootstrap Isis as a webapp

o.a.i.runtimes.dflt

bytecode

 

o.a.i.runtimes.dflt.bytecode

dflt

o.a.i.core

isis-cglib-bytecode

Suggest no longer positioned as 'default'; since JDO for example does not require this module.

o.a.i.runtimes.dflt.bytecode

identity

TO CONFIRM: Rolled up into oai.core:isis-runtime; is the new 'default'

o.a.i.runtimes.dflt.bytecode

javassist

o.a.i.core

isis-javassist-bytecode

 

o.a.i.runtimes.dflt

monitoring

o.a.i.monitoring

isis-monitoring

Probably to be retired.

o.a.i.runtimes.dflt

objectstores

Delete module; due to flattening

o.a.i.runtimes.dflt.objectstores

dflt

o.a.i.objectstore

isis-inmemory-objectstore

 

o.a.i.runtimes.dflt.objectstores

jdo

o.a.i.objectstore

isis-jdo-objectstore

 

o.a.i.runtimes.dflt.objectstores

jdo-applib

o.a.i.objectstore

isis-jdo-objectstore-applib

 

o.a.i.runtimes.dflt.objectstores

jdo-datanucleus

o.a.i.objectstore

isis-jdo-objectstore-datanucleus

 

o.a.i.runtimes.dflt.objectstores

jdo-metamodel

o.a.i.objectstore

isis-jdo-objectstore-metamodel

 

o.a.i.runtimes.dflt.objectstores

nosql

o.a.i.objectstore

isis-nosql-objectstore

 

o.a.i.runtimes.dflt.objectstores

sql

o.a.i.objectstore

isis-sql-objectstore

 

o.a.i.runtimes.dflt.objectstores

sql-impl

o.a.i.objectstore

isis-sql-objectstore-impl

 

o.a.i.runtimes.dflt.objectstores

sql-tests-common

o.a.i.objectstore

isis-sql-objectstore-tests-common

 

o.a.i.runtimes.dflt.objectstores

sql-tests-served

o.a.i.objectstore

isis-sql-objectstore-tests-served

 

o.a.i.runtimes.dflt.objectstores

xml

o.a.i.objectstore

isis-xml-objectstore

 

o.a.i.runtimes.dflt

profilestores

Delete module; due to flattening

o.a.i.runtimes.dflt.profilestores

dflt

o.a.i.profilestore

isis-inmemory-profilestore

 

o.a.i.runtimes.dflt.profilestores

sql

o.a.i.profilestore

isis-sql-profilestore

 

o.a.i.runtimes.dflt.profilestores

xml

o.a.i.profilestore

isis-xml-profilestore

 

o.a.i

progmodels

Delete module; due to flattening

o.a.i.progmodels

dflt

isis-progmodel-dflt

TO CONFIRM: rolled up into oai.core:isis-metamodel

o.a.i.progmodels

groovy

o.a.i.progmodel

isis-progmodel-groovy

 

o.a.i.progmodels

groovy-applib

o.a.i.progmodel

isis-progmodel-groovy-applib

 

o.a.i.progmodels

groovy-metamodel

o.a.i.progmodel

isis-progmodel-groovy-metamodel

 

o.a.i.progmodels

wrapper

o.a.i.progmodel

isis-progmodel-wrapper

 

o.a.i.progmodels

wrapper-applib

o.a.i.progmodel

isis-progmodel-wrapper-applib

 

o.a.i.progmodels

wrapper-metamodel

o.a.i.progmodel

isis-progmodel-wrapper-metamodel

 

o.a.i

isis.viewer

Delete module; due to flattening

o.a.i.viewer

bdd

o.a.i.viewer

isis-bdd-viewer

 

o.a.i.viewer

bdd-common

o.a.i.viewer

isis-bdd-viewer-common

 

o.a.i.viewer

bdd-concordion

o.a.i.viewer

isis-bdd-viewer-concordion

 

o.a.i.viewer

bdd-concordion-tck

o.a.i.viewer

isis-bdd-viewer-concordion-tck

 

o.a.i.viewer

dnd

o.a.i.viewer

isis-dnd-viewer

 

o.a.i.viewer

html

o.a.i.viewer

isis-html-viewer

 

o.a.i.viewer

junit

o.a.i.viewer

isis-junit-viewer

 

o.a.i.viewer

junit-tck

o.a.i.viewer

isis-junit-viewer-tck

 

o.a.i.viewer

restfulobjects

o.a.i.viewer

isis-restfulobjects-viewer

 

o.a.i.viewer

restfulobjects-applib

o.a.i.viewer

isis-restfulobjects-viewer-applib

 

o.a.i.viewer

restfulobjects-viewer

o.a.i.viewer

isis-restfulobjects-viewer-viewer

 

o.a.i.viewer

restfulobjects-tck

o.a.i.viewer

isis-restfulobjects-viewer-tck

 

o.a.i.viewer

scimpi

o.a.i.viewer

isis-scimpi-viewer

 

o.a.i.viewer

scimpi-dispatcher

o.a.i.viewer

isis-scimpi-viewer-dispatcher

 

o.a.i.viewer

scimpi-servlet

o.a.i.viewer

isis-scimpi-viewer-servlet

 

o.a.i.viewer

scimpi-tck

o.a.i.viewer

isis-scimpi-viewer-tck

 

o.a.i.viewer

wicket

o.a.i.viewer

isis-wicket-viewer

 

o.a.i.viewer

wicket-model

o.a.i.viewer

isis-wicket-viewer-model

 

o.a.i.viewer

wicket-ui

o.a.i.viewer

isis-wicket-viewer-ui

 

o.a.i.viewer

wicket-viewer

o.a.i.viewer

isis-wicket-viewer-viewer

 

o.a.i.viewer

wicket-tck

o.a.i.viewer

isis-wicket-viewer-tck

 

o.a.i

security

Delete module; due to flattening

o.a.i.security

isis.security.dflt

o.a.i.core

isis-noop-security

 

o.a.i.security

file

o.a.i.core

isis-file-security

 

o.a.i.security

ldap

o.a.i.security

isis-ldap-security

 

o.a.i.security

sql

o.a.i.security

isis-sql-security

 

o.a.i

isis.tck

o.a.i.core

isis-tck

 

o.a.i

isis.tck-dom

o.a.i.core

isis-tck-dom

 

o.a.i

isis.tck-fixture

o.a.i.core

isis-tck-fixture

 

o.a.i.skins

classic-skins

o.a.i.core

isis-site-skin

 

o.a.i

quickstart-archetype

o.a.i.archetypes

isis-archetype-wicket-restful-jdo

each archetype represents an 'edition' of Isis; separately releasable

o.a.i

quickstart-archetype

o.a.i.archetypes

isis-archetype-scimpi-nosql

 

o.a.i

quickstart-archetype

o.a.i.archetypes

isis-archetype-dnd-xml

 

o.a.i

quickstart-archetype

o.a.i.archetypes

isis-archetype-dnd-junit-bdd

 

Original text that initiated the discussion


At the moment it's a daunting task to fully verify all the components of the framework are working correctly prior to pushing out a release. I suppose that wouldn't be so much of a concern if we had better automated tests, but, hey, that's how things are.

Moreover, frankly, some of the modules are best considered spikes and probably don't constitute something that we would consider production-ready. Or, at least, they haven't been used in a real-world context, so it's not possible to say whether they are really fit-for-purpose. I include here quite a lot of the stuff that I have worked on over the last few years, eg the wrapper-progmodel, the groovy progmodel, probably also the JUnit viewer and BDD viewer. Now that we are a top-level project, I'd like it that the code we put out is thought of as production ready.

In order to make the framework easier to release, I propose that we use Maven profiles to be able to release subsets of modules, that a given contributor can stand behind and say: "yes, those modules are working and are fit for general consumption". Each release would consist of the certain core modules, along with selected additional viewers and object stores.

For example, we might have:

  • v0.3.1 core + objectstore-jdo + viewer-wicket + viewer-restfulobjects // a "wicket/jdo release" - eg tested and released by Dan
  • v0.4.0 core + objectstore-nosql + viewer-scimpi // a "scimpi/nosql release" - eg tested and released by Rob
  • v0.5.0 core + objectstore-dflt + objectstore-xml + viewer-dnd // a "dev release" - eg tested and released by Rob
  • v0.6.0 core + objectstore-jdo + viewer-wicket + viewer-restfulobjects // another "wicket/jdo release"
  • v0.7.0 core + objectstore-sql + viewer-html // a "html/sql release" - eg tested and released by Kevin
  • v0.8.0 core + objectstore-jdo + viewer-wicket + viewer-restfulobjects // another "wicket/jdo release"

Whenever a release goes out, we would update the site to indicate the most recent version of the components.

Now, when I say "release", what I actually mean here is the deployment of binary artifacts up to the Maven central repo. This, after all, is what most users/would-be users in the community would use and consider a release. However, Apache's own formal definition of "release" is actually the source code release ... this is what the VOTE mechanism is for. I don't see this changing... the vote basically says that the software complies with all the legal license stuff etc. The whole codebase is tagged with that release number, and the generated src.zip is a zip of this release.

One benefit of this is that it allows the deployment of other modules to be performed "after the fact". For example, suppose that I (Dan) puts out the v0.3.1 release as above, and then Rob later on tests the scimpi viewer in that tag and finds it works well. He can (I think) push the release of the scimpi viewer up to Maven central repo.

As I see things there are several benefits to this scheme:

a) (as already noted) the user community will only see binary releases that are known to be of production ready. This should mitigate the "is it safe to use this component" worry
b) (as hinted at) it should be possible for individual contributors to put out releases of their modules more rapidly
c) we get visibility of which modules aren't being released; for example, we might say that if a module hasn't been released by anyone for 18 months, say, then it's probably time to remove it from the codebase.

  • No labels

2 Comments

  1. Can't we flatten out the runtime-dflt too? Something like:

    runtime-dflt/runtime

    runtime

    runtime-dflt/testsupport

    testsupport

    runtime-dflt/webapp

    webapp-geronimo

    runtime-dflt/webserver

    webserver-jetty

    1. I'm not sure it's required; these will always make up the core release.

      And.. if we did do that, then to be consistent we also ought to flatten out all of org.apache.isis:core aggregator module, which is 6 submodules.