In this document the Eclipse RDF4J project workflow and developer best practices are explained. It contains information on how to create branches, tag releases, manage pull requests, create and schedule issues, and so on. Some of this information is targeted specifically at the project lead(s), other information is relevant to every committer.
A PATCH release (2.2.1, 2.2.2, etc.) is a release that contains only bug fixes that are backwards compatible.
A MINOR release (2.0, 2.1, 2.2, etc.) is a release that can contain improvements and new features but makes no backward-incompatible changes to existing functionality.
A MAJOR release (1.0, 2.0, 3.0, etc) is a release that can contain changes to the public API that are not backward compatible.
It is currently not fully specified what the boundaries of the RDF4J public API are. Until this is resolved (see issue #619), we allow changes to public or protected methods/classes/interfaces in minor releases under the following conditions:
any renamed interface is declared an extension of the old interface. The old interface is marked deprecated with Javadoc containing a reference to the new name;
any renamed class is declared a superclass of the old class. The old class is marked deprecated with Javadoc containing a reference to the new name;
any renamed member is added next to the old member name. The old member is declared deprecated with Javadoc containing a reference to the new name.
These conditions are to ensure that existing user code will continue to work when upgrading to the new release. If there is any doubt about a change being backwards-compatible, it can not be made part of a minor release.
For patch releases we never allow changes in the public API, unless the change is specifically to fix a bug that aligns the actual behavior of the code with the publicly documented behavior.
Only release branches (more on those later) include the full major.minor.patch
version numbers included with releases. The major and minor version of the master and
develop branches do not include a patch number and always have a SNAPSHOT tag.
The master and develop versions always matches the pattern MAJOR.MINOR-SNAPSHOT.
The master version always has the same major and minor number as the latest
release while the develop version uses the next expected major/minor
release number, such as 2.1-SNAPSHOT and 2.2-SNAPSHOT respectively
(after a 2.1.x release, but before any 2.2.x releases are made public).
Every issue, no matter how small, gets its own issue
ticket, and its own branch while
under development. The milestone label of the issue is set to the planned
release version for the issue, but that could change by the time a PR is
merged. Issue branch names are always prefixed with GH-<issuenumber>,
followed by one or two dash-separated keywords for the issue.
For example: GH-1664-transformation-servlet is the branch for a fix for issue
GH-1664, which has to do with the transformation servlet.
RDF4J uses a git branching model where collaborative feature development takes
place on branches from the develop branch. This is where all development for
the next (minor or major) release happens.
Once a issue is complete and tested, a Pull Request (PR) should be created
for peer review. The Pull Request description should start with a link to the
issue that is addressed by the PR. If the issue is part of a larger feature,
the PR should be branched from (and target) the corresponding branch. If the
issue is a new feature in and of itself, the PR should be branched from (and
target) the develop branch. If the issue is a bug fix, the PR should be
branched from (and target) the master branch.
Tip: when starting work on an issue, and you are unsure if it will be a new
feature or “just” a bug fix, start by branching from the master branch. It
will always be possible to merge your issue branch into develop later if
necessary. However, if you start from develop, merging into master will not
be possible, and you’re therefore committed to the next minor/major release.
If the change is a bug fix, contains no new features, and does not change any public or protected APIs:
Create a Pull Request that targets the master branch.
Peers and project committers now have a chance to review the PR and make suggestions.
Any modifications can be made to the issue branch as recommended.
Once any necessary changes have been made, project committers can mark the PR as approved.
Project committers should then determine what patch release this fix will be included in by updating the milestone label of both the PR and the issue.
Only when a Pull Request is approved and scheduled for the next patch release it should be merged into the master branch then
After a PR has been merged into the master branch, the master branch should
then be merged into the develop branch by the project committer that merged the PR,
any conflicts (such as due to new features) should be resolved.
This can be done from the command line from a clean checkout as follows:
Pull Requests that add a self contained new feature to the public API follow
the same steps as a Patch Request but should start from and target the develop branch.
Only PRs that have been scheduled for the next minor release
should be merged into the develop branch.
Project committers that are contributing to a branch should periodically
pull changes from the develop branch (either by merging or rebasing) to minimize conflicts later on.
Once a features is complete another PR should be created using the feature branch and target the develop branch.
Then follow similar steps to a patch request to schedule and merge into develop.
Minor and major releases require a formal release
review, and because
this is the case, they need to be planned well in advance, and the project lead
needs to manage what can go into each release, and prepare necessary
documentation (both technical and legal) for review. For this reason approved
Pull Requests may stay open (not scheduled or merged) for some time until a
release plan that incorporates these changes and any required documentation is
in place. The comment section in the PR can be used to keep everyone informed
of the progress.
Some generic sources of information about projects hosted by Eclipse: