eXist Native XML Database
This is the GitHub for the eXist Native XML Database.
If you're looking to work with the eXist source code, you've come to the right place. If not, you're probably looking for the eXist Documentation.
If you're looking for help or discussion, visit the eXist community mailing lists.
Information for Developers
Building eXist from Source
eXist itself is written predominantly in Java 6. The build system is Apache Ant.
To build eXist:
- Checkout the Git Repository
- Execute Ant to compile eXist
$ git clone email@example.com:eXist-db/exist.git $ cd exist $ git checkout master $ ./build.sh
In the above example, we switched the current (checked-out) branch from
master. We use the GitFlow for eXist process:
developis the current (and stable) work-in-progress (the next release)
masteris the latest release
The choice of which to use is up to you.
HINT: In the example above, we use the SSH form of the GitHub repo URL to clone eXist. However, if you're behind a HTTP proxy and your organisation doesn't allow outgoing SSH connections, try the HTTPS URL for our GitHub repo https://github.com/eXist-db/exist.git.
From here, you now have a compiled version of eXist that you may use just as you would an installed version of eXist, however it may be desirable to package this up for easy installation elsewhere. If you wish to create a simple ZIP distribution of eXist, run:
$ ./build.sh dist-zip
To build a full Installer for eXist, you'll need to have IzPack installed. Set your path to IzPack in
exist/build.properties and run:
$ ./build.sh installer
Otherwise, you may wish to deploy eXist into a Web Application Server as a WAR file. We provide a build for that, too:
$ ./build.sh dist-war
For more build options, see the eXist Build Documentation.
Contributing to eXist
We welcome all contributions to eXist!
We strongly suggest that you join the eXist-development mailing list and also subscribe to the eXist-commits mailing list, so that you can collaborate with the eXist team and be kept up to date with changes to the codebase.
If you wish to contribute, the general approach is:
- Fork the repo on GitHub
git cloneyour fork
- Make sure you've GitFlow AVH Edition installed
git flow initon the cloned repo using these settings.
- Use Git Flow to start a hotfix or feature i.e. git flow feature start my-magic-feature
- Do your stuff! :-)
- Commit to your repo. We like small, atomic commits that don't mix concerns.
- Use Git Flow to finish the
feature. WARNING: If you're using a
hotfix, please don't tag it; there's no way to send an unknown branch from your fork upstream using GitHub's Pull Requests.
- Push your hotfix or feature branch to your GitHub using GitFlow (
git flow feature publish *my-magic-feature*)
- Send us a Pull Request
Pull Requests are reviewed and tested before they're merged by the core development team. However, we have one golden rule, even within the core team: never merge your own pull request. This simple-but-important rule ensures that at least two people have consisered the change.
- Only change what you need to. If you must reformat code, keep it in a seperate commit to any syntax or functionality changes.
- Test. If you fix something prove it, write a test that illustrates the issue before you fix the issue and validate the test. If you add a new feature it needs tests, so that we can understand its intent and try to avoid regressions in future as much as possible.
- Make sure the approriate licence header appears at the top of your source code file. We use LGPL v2.1 for eXist and strongly encourage that, but ultimately any compatible OSI approved license without further restrictions may be used.
- Run the full eXist test suite. We don't accept code that causes regressions.
Do I work on a bug-fix using a
feature or a
If you want to contribute a bug-fix, you need to consider whether this is a
feature or a
hotfix in GitFlow terminology.
Making the determination involves considering how the bug-fix is to be applied and how it is to be applied. First, you should carefully read the "Feature branches" and "Hotfix branches" sections from A successful Git branching model.
If you're still unsure, consider:
- The bug-fix is a hotfix if it is critical and needs to go into a very soon to be released revision version i.e. 2.1.n to address an immediate production issue.
- Otherwise it is a feature, i.e. its just standard development towards the next release of eXist.
Even for a bug-fix you should most probably use a
feature. If you're certain you want to create a
hotfix, please consider discussing first via the
exist-development mailing list.
git-flow init settings
When we started working with the eXist repo we needed to configure it for GitFlow:
$ git flow init Which branch should be used for bringing forth production releases? - master Branch name for production releases: [master] Branch name for "next release" development: [develop] How to name your supporting branch prefixes? Feature branches? [feature/] Release branches? [release/] Hotfix branches? [hotfix/] Support branches? [support/] Version tag prefix?  eXist-
develop branch is created, and checked out.
Verify it like this:
$ git status # On branch develop
As we have already started with GitFlow, when you run
git flow init, you'll get slightly different prompts--but the same answers apply!
You must use the following settings:
$ git flow init Which branch should be used for bringing forth production releases? - develop Branch name for production releases:  master Which branch should be used for integration of the "next release"? - develop Branch name for "next release" development: [develop] How to name your supporting branch prefixes? Feature branches? [feature/] Release branches? [release/] Hotfix branches? [hotfix/] Support branches? [support/] Version tag prefix?  eXist-