This chapter pulls together various policy documents relating to the development of Apache Isis'.

Versioning Policy

Semantic Versioning

Starting from v1.0.0, Apache Isis has adopted semantic versioning for its versioning policy.

Version numbers are in the form x.y.z:

  • x is bumped up whenever there a breaking API change

  • y is bumped up whenever there is a new feature that does not break API

  • z is bumped up for minor bug fixes.

This scheme would be adopted for both core and components.

Version ranges

Version ranges may not be used. If necessary, end-users can use <dependencyManagement> elements to have combine components built against different versions of core.

That said, this can introduce instability and so generally we recommend that end-users configure the maven-enforcer-plugin and its DependencyConvergence rule. This will help avoid "jar hell" (components having conflicting dependencies of core).

If there is a conflict, we would ask that end-users engage with Apache Isis committers to have an updated version of the component(s) pushed out.

Git Policy

These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:

  • git commits form an acyclic graph, with each commit pointing to its parent commit (or commits, if a merge)

  • a branch is merely a pointer to one of these commits; git calls the main branch master

  • git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.

For more background reading, see:

And, of course, there is loads of good advice on stackoverflow.com


There are many ways of using Git, but the Apache Isis committers have adopted the following workflow:

  • create a topic branch for a feature

    git checkout -b ISIS-999
  • periodically, push the branch to origin (for safekeeping):

    git push origin ISIS-999
  • rebase the topic branch periodically on master.

    How often you do this will depend on whether you are collaborating with others on the feature. You need to ensure that your co-worker has no outstanding work before you do this; otherwise it’ll create merge conflict hell for them:

    git checkout master
    git pull
    git checkout ISIS-999
    git rebase master
    git push origin ISIS-999 --force
  • when feature is complete, rebase once more (as above), then switch to master and perform a merge --no-ff:

    git checkout master
    git merge --no-ff ISIS-999
  • finally, remove the branch

    git branch -d ISIS-999
    git push origin --delete ISIS-999

This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to master to see the ultimate impact of the changes (acting a bit like a summary).

Commit message

The minimum we expect in a commit messages is:

ISIS-nnn: brief summary here

- optionally, longer details
- should be written here
- in bullet points

where ISIS-nnn is a ticket raised in our JIRA issue tracker.

For non-committers we typically expect more detail again; see the contributing page for the longer format recommended for contributors to use.