Contributing Code to DSpace Software

This page provides specific guidelines on how to contribute your code to DSpace, and details how the code review/acceptance process works.

Developers - See also the Developer Guidelines and Tools for hints/tips on using popular IDEs to develop with DSpace.

Contribution Quick Checklist

This page has a lot of great information on it. But, if you just need the high level overview, here it is. NOTE: the checkboxes below are here for "decorative" purposes, and aren't really intended to be used. If you'd like, and you find it helpful, you may print this page and then check off each step as you proceed with your contribution. Happy coding, and please ask for help if you find you need it!

Overview of Code Approval Process – How to get your Code into DSpace!

0. Share Early, Share Often!

The overriding mantra is share early, share often. Here are a few things to consider before you begin working on your code:

1. Make your code available (preferably in GitHub) and create a ticket in our Issue Tracker

Once your code is ready, you must make your code available to the DSpace Committers Group for review. The easiest way for us to review your code is by putting your code into GitHub. Then, submit a "Pull Request" to our GitHub repository (see also Development with Git). Alternatively, if you are not yet comfortable with GitHub, you may create a patch (and upload it to our DSpace Issue Tracker). However, please be aware that submitting a patch may delay the review process (see below note)

In either case, you must also create a new ticket in our DSpace Issue Tracker. This ensures that the DSpace Developers are notified of your contribution, and acts as a place for us to comment on the work or make suggestions for improvements.

Code contributions that meet certain standards are much more likely to be accepted immediately. For a list of our current standards, please read through the Code Contribution Guidelines#Code Contribution Standards section below.

When making a code contribution, at the very least you should create a new ticket in our DSpace Issue Tracker. In that issue you should provide information as to why you feel this code is a worthwhile contribution (e.g. describe the bug it fixes or a use case that it meets). You can submit your code as an attachment to that ticket (not recommended, see below), or submit it as a Pull Request to our GitHub code repository (highly recommended).

We highly recommend submitting a GitHub Pull Request (see Development with Git for hints/tips), which mentions the ticket by number (e.g. DS-1234).  In order to add any new feature to DSpace, a Pull Request must be generated (by someone). So, if you are able to create and submit the Pull Request, it makes it that much easier for the Committers to review and accept the changes. If you are unable to create the Pull Request, then the review process may be delayed, as we will need to locate a "steward" for your contribution, i.e. someone who is willing and able to create the necessary Pull Request on your behalf.

When the next release of DSpace is getting close, the Committers will set a "Feature Contribution Deadline" date, after which no new feature submissions will be accepted for that release. The reason for this is that the Committers need time to review & stabilize the current code before the next release can be completed. Make sure to check the Next Release Status page for details on when the next "Feature Contribution Deadline" is. Please note that bug fixes are still accepted after the "Code Contribution Deadline", as they will help to stabilize the upcoming release.

2. Code Review Process

Once the code is made available, the Committers Group will take time to review the work and provide feedback/comments. Usually, one (or more) committers who are interested in this work will contact you and discuss any feedback we have, and whether or not there would need to be some general changes before we could accept it. Some patches/features are readily accepted (because they are stable and look good), others may require more work (if there are concerns or issues that Committers notice).

The timeframe of a code review will vary, based on how much time the Committers have. Smaller changes may be reviewed within days, while larger changes/features may take many weeks to do a full review. All Committers are volunteers and only have a small amount of time to provide to the project in a given week. We will make every effort to get back to you with feedback within a few weeks. But, if you haven't heard anything, feel free to ask!

When we review your code, we are mostly ensuring it generally follows our Code Contribution Guidelines#Code Contribution Standards. However, there are a few other things we generally check for:

  • The code is well commented (e.g. has JavaDocs)
  • The code follows our Code Style Guide (only required for DSpace 7.x and above)
  • The code provides Unit and/or Integration Tests (see Code Testing Guide)
  • The code is stable and has no stability or security concerns
  • The code is properly using existing APIs, etc.
  • The code is not too specific to one institution's local policies or workflows. (I.e. we will review the code to ensure it looks to be generally useful to most institutions, or configurable enough such that others can change it to match their own local policies/workflows)
  • Any third-party tools/libraries used by your code have compatible open source licenses. See Code Contribution Guidelines#Licensing of Contributions

3. Reworking Code (if necessary) & Next Steps

After the code review & feedback, interested Committers may help you to rework the code (if needed). They'll also provide you with next steps on getting the code into DSpace. If it can be accepted immediately, it will be. If not, we'll try to help figure out the best route forward.

As our Committers are all volunteers, they don't always have the time to rework code changes for you. If you want your code change accepted in a timely manner, please offer to make the changes yourself (otherwise your patch suggestion may wait in a "holding queue" until someone has enough time to work on any necessary fixes).

If you are unsure of next steps, please let us know by adding a comment to your issue in the Issue Tracker. Communication is absolutely necessary to ensure that we can help you rework anything that needs reworking. If we don't hear from you, we'll assume you are hard at work. So, if you've run into issues, please let us know! If, locally, you don't have the time or expertise to do the rework that is necessary, also let us know. We can try to locate a community developer to help out, and/or ask both the Committers Team and the DSpace Community Advisory Team if they know of any interested developers with time to spare.

4. Acceptance!

Once your code is accepted, it will be released in the next version of DSpace software! It is time to celebrate, as your name will be added to the prestigious list of DSpace Contributors!

Code Contribution Standards

Code contributions that meet the following standards are much more likely to be accepted. If you don't understand any of these standards, please contact us – we'll be glad to explain or help.

Contribution Checklist

When you contribute to DSpace, please be sure that your submission adheres to the points in this checklist. The DSpace Committers need you to do this to keep quality of the DSpace code high and their work manageable.

  1. Any changes must be compliant with the supported version of Java (e.g. for DSpace 7, Java 11 compliance is required)
  2. Your code must adhere to our Java Code Style Guide. Most major IDEs can easily import our Checkstyle configurations to ensure alignment with this code style.
    1. Your code should be well commented with Javadoc (required for all classes, public methods and larger private/protected methods).
  3. Your code must provide unit/integration tests for new features, bug fixes or improvements per our Code Testing Guide.
  4. If your contribution adds new third-party tools or libraries, they must adhere to licensing requirements to be included. Refer to the Code Contribution Guidelines#Licensing of Contributions below
  5. User interface changes must be internationalised (see the Internationalization Support (I18nSupport) guide)
  6. User interface changes should have a W3C WCAG Conformance Level of "Double-A"
  7. Your code must come with Documentation. Minimally, technical documentation must be part of the system docs – see Code Contribution Guidelines#Documentation Contributions below. Ideally, we'd also like User/Usage Documentation.
  8. Ideally, new features should be configurable (i.e. generalized so as to not be specific to one institution's needs/use cases).  Any new configurations should have sane defaults which can be overridden (as needed) in a site's local.cfg file.
  9. Add appropriate WARN, INFO and DEBUG-level logging. Use the included Apache Log4J toolkit, in concert with the org.apache.logging.log4j.LogManager class to do this.
    1. Provide informative log statements and/or the entire Throwable exception. For example, "log.error('My custom error message', e)" is more useful than "log.error(e.getMessage(), e)"
  10. Retain backwards compatibility where possible. If there are questions/concerns about this, let us know. There are always exceptions.
  11. No database schema changes unless absolutely necessary to support a new feature. See Code Contribution Guidelines#Database schema changes below.
  12. If your code makes changes to the database schema or content, and you are patching more than one branch (for example, dspace-6_x and master), see Code Contribution Guidelines#Patching multiple branches below.

If there are questions/concerns about any of these guidelines, let us know on the 'dspace-devel' list. We are willing to make exceptions in some areas, if exceptions are necessary.

Omission of one or more of these items is likely to result in the a request for further work. See the Overview of Code Approval Process above, for more information.

Licensing of Contributions

Any third-party libraries (e.g. JARs / Maven Dependencies) required to compile or run DSpace must be included. The license of any required jar/dependency MUST be compatible with BSD. It must not prevent any commercial use of DSpace, nor have any impact on the rest of the code by its inclusion. It is not acceptable to require additional downloads of JARs/dependencies to make DSpace compile or function.

Non-Java third-party web frameworks or tools (e.g. XSLT, CSS, Images) should follow these same licensing guidelines.

Examples of acceptable licenses:

Examples of unacceptable licenses:

DuraSpace feels it is important for commercial entities and service providers to be able to customize the entire codebase and redistribute/repackage/sell it in a binary form. GPL licenses prevent this, as noted in the following FAQ questions:

In addition, the Apache Software Foundation has a good explanation of why they are also forced to avoid GPL-based (copyleft) licenses because of its one-way compatibility with Apache License 2.0:

"This licensing incompatibility applies only when some Apache project software becomes a derivative work of some GPLv3 software, because then the Apache software would have to be distributed under GPLv3. 

We avoid GPLv3 software because merely linking to it is considered by the GPLv3 authors to create a derivative work. We want to honor their license. Unless GPLv3 licensors relax this interpretation of their own license regarding linking, our licensing philosophies are fundamentally incompatible. This is an identical issue for both GPLv2 and GPLv3."

While DSpace is released under BSD licensing, the same issues exist between BSD licenses and GPL-based licenses.

JDBC drivers for databases are an exception since:

Database schema changes 

Database schema changes will be done only on major revisions to the source; this is when the version number takes the form x.0 (e.g. 2.0). When making patches which cause schema changes, it is necessary to update all of the relevant SQL/migration files with your sequences, tables, views etc. 

Patching multiple branches

When you patch the same issue in multiple branches, database changes require special attention.  This advice applies to both schema changes and content changes.

Documentation Contributions

All new features require documentation before they will be accepted. You may send us code before documentation is completed, but we will be unable to accept that code into DSpace until it is properly documented. Bug fixes may not require documentation, unless they somehow make a modification which changes how DSpace functions.

All documentation is now built in a special section of the Wiki at DSpace Documentation. Therefore, the best way to send us Documentation is to actually create a new page(s) in this DSpace Wiki. You should link these Wiki page(s) to your issue in our DSpace Issue Tracker. We'll move them over into the official DSpace Documentation area once you code has been accepted.