eXist-db Developer Manifesto

Communication

Communication between developers and within Open Source projects can be a hard thing to achieve effectively, but to ensure the success of the project and contributions, we must all strive to improve on communicating our intentions.

Public and open discussion of all new features and changes to existing features must always be undertaken. eXist-db is a community project and the community must be invited to provide input and feedback on development. Development discussions take place through the eXist-db Development mailing list.

If conflicts of interest occur during discussion, they must be resolved before code changes are made. If conflicts cannot be resolved by the community, usually one of the core maintainers acts as a moderator. Core maintainers are contributors who feel responsible for the project as a whole and have shown it in the past their commitment and support. Right now this includes: Pierrick Brihaye, Wolfgang Meier, Leif-Jöran Olsson, Adam Retter and Dannes Wessels. We name those people, so you know who to talk to, but the list is in no way exclusive and may change over time.

Maintainability

All code accepted must be maintainable. Otherwise there is the possibility that it will grow stale and, without maintainers, will be removed from the code base.

To ensure a happy future for the code base, each contributor has a responsibility to ensure:

• New code and bug-fixes must be accompanied by JUnit/XQuery/XSpec test cases. This helps us understand intention and avoid regressions.

• Code must be appropriately commented (including javadoc/xqdoc), so the intention is understood. Industry standard code formatting rules must be followed. This helps us read and understand contributions.

• Code must be tagged with the developers name and email address. This helps us contact contributors/maintainers should issues arrive.

• Consider the maintainability of new features: will you maintain and support them over years? If not, who will? How do you communicate what is required?

Developing

• Follow Industry Standard coding conventions.

• eXist-db is now developed atop Sun Java 8, so make use of Java 8 features for cleaner, safer and more efficient code.

• New Features must be generic and applicable to an audience of more than one or two. Consider whether the eXist-db community would see this as a valuable feature (you should have already discussed this via the eXist-db Development mailing list). If a feature is just for you and/or your customer, it may have no place in eXist-db's main code base.

• Major new features or risky changes must be developed in their own branch. Once tested (this must include user testing) they may then be integrated back into the main code base.

• Follow a RISC like approach to developing new functions. It is better to have a single function that is flexible than multiple function signatures for the same function. Likewise, do not replace two functions by offering one new super function. Functions should act like simple building blocks that can be combined together.

• The use of Static Analysis tools is highly recommended. These tools reduce risk, and are valuable even to the most highly skilled developers. Such tools include Checkstyle, FindBugs and PMD.

Before Committing

• TEST, TEST and TEST again! See last section how to do this.

• Execute the JUnit test suite to ensure that there are no regressions. If there are any regressions, do not commit!

• Execute the XQTS test suite to ensure that there are no regressions. If there are any regressions, do not commit!

• If you are working in an area of performance, there is a Benchmark test suite that you should run.

• When effecting major changes, make sure all the demo applications which ship with eXist-db are still working as expected. Testing of the main user interfaces, including Java WebStart client and WebDAV, helps to avoid surprises at release time.

• Documentation, whilst often overlooked, is critical in getting users to accept and test any new feature. If you add features without documentation they are worthless to the community.

• Have a look at the Code Review Guide and take its recommendations at heart!

• Atomicity! Please consider how you group commits together. A feature should be contributed as an atomic commit, this enables co-developers to easily follow and test the feature. If you need to clean up existing code during development, please commit this labelled 'cleaning up'. This makes your final commit much more concise.

• If possible, without breaking existing functionality, it can be useful to break very large commits into a few smaller atomic ones, spanning a couple of days. This allows other users to test and help identify any parts of your code which might introduce issues.

• Commit tagging helps us to generate lists of what has changed between releases. Please prefix your commit messages with an appropriate tag:

  • [bugfix]

  • [lib-change]

  • [feature]

  • [ignore]

  • [format-change]

  • [documentation]

  • [documentation-fix]

  • [performance]

  • [testsuite]

  • [building]

  The change log scripts will ignore any messages which do not start with one of the tags above or whose tag is [ignore].

Finally

Open Source projects are almost but quite not a democracy. Breaking, unknown and/or untested commits cause a lot of pain and lost hours to your fellow developers.

Whilst we of course wish to encourage and nurture contributions to the project, these have to happen in a manner everyone involved in the project can cope with. However, as an absolute last measure, if developers frequently fail to adhere to the Manifesto then Commit access to the eXist-db repository shall be revoked by the core developers.

How to enable all and test

It is essential that none of the existing code breaks because of your commit. Here is how to be sure all code can be built and tested:

1. Edit conf.xml (or actually the original file conf.xml.tmpl)

   1. Uncomment all (really, all) built-in modules under Xpath /exist/xquery/builtin-modules

   2. Activate the spatial index by uncommenting the index-module spatial-index under Xpath /exist/indexer/modules (the corresponding function module is uncommented in the first step.

2. Edit local.build.properties and switch on all modules

   1. The Oracle module can be left switched off, the required jar is a bit difficult to download

   2. Switch all modules on with the command

      cat build.properties | sed 's/false/true/g' > local.build.properties