Developers - See also the Developer Guidelines and Tools for hints/tips on using popular IDEs to develop with DSpace. |
The overriding mantra is share early, share often. Here are a few things to consider before you begin working on your code:
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 (just create your own account – it's free!). Then, submit a "Pull Request" to our GitHub repository (see 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).
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 Standards section below. |
The best way to inform us of your code contribution is by entering a new issue into 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 either submit a corresponding "Pull Request" to our GitHub repository (recommended, see Development with Git) or upload any files/patches to that issue directly. We will then review & comment on your code in that same area (and it will automatically send you an email with our comments). |
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. |
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 Standards. However, there are a few other things we generally check for:
|
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. |
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 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.
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.
dspace.cfg
file. Make sure you only patch this if you change involved new configuration parameters in it, and make sure you have good default values for them. Don't accidentally include your own local configuration parameters (e.g. host name etc) in the patch! If the new feature is in any way specific to a particular application (e.g. open access, theses), it should be switched off by defaultwebui.submit.thesisstep
, and webui.submit.thesisstep.color
. If webui.submit.thesisstep = false
, the submission process should not be affected for those not using DSpace for e-theses. Also, if your code finds that webui.submit.thesisstep
is missing, it should assume a default of 'false' so that after an update, previous installations of DSpace behave as expected, and they do not have to add that parameter to their dspace.cfg
.org.dspace.core.LogManager
class to do this. See org.dspace.app.webui.servlet.DSpaceServlet
for an example of how to do this.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 patch not being applied and returned to you for further work. See the Overview of Code Approval Process above, for more information. |
Your code needs to follow the Sun Java code conventions with the following minor modifications:
Your code should be well commented with Javadoc (including package and class overviews). All code contributions must come with Documentation. At a bare minimum, this should include Technical Documentation covering all configuration options and/or setup. See Documentation Contributions below for more details.
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: |
JDBC drivers for databases are an exception since:
Database schema changes will be done only on major revisions to the source; this is when the version number takes the form x.y (e.g. 1.3). When making patches which cause schema changes it is necessary to update all of the relevant SQL files with your sequences, tables, views etc. (in /dspace/etc):
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.
As of 1.7.0, the 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.