Page History
...
- Create a ticket in the DSpace Issue Tracker (describe your contribution, how to use it, and perhaps some use cases).
- Make sure your code adheres to our Code Style Guide (only required for DSpace 7.x or above)
- Write unit/integration tests per our Code Testing Guide (only required for DSpace 7.x or above)
- Submit your code via GitHub. It is HIGHLY recommended to do so via a GitHub Pull Request (see GitHub's "About Pull Requests", or our notes on Development with Git), which references your newly created ticket by number (e.g. DS-1234). If you are uncomfortable with Git/GitHub, you may instead attach a patch to the ticket you created. Be warned that the review/approval process for patch files is often much slower, as we first must locate someone to create a Pull Request on your behalf.
- Ideally submit your code or ideas early on before it turns into a massive project. Larger code changes take a very long time to understand, review and test. Starting the discussion early (or breaking the changes up into several smaller changes) can make it much easier to get your code accepted.
- Review your own code. Does it follow our Contribution Checklist? Does it need Documentation? If you are using any third party tools/APIs, do they all have an acceptable Open Source License (see Licensing of Contributions)? The Committers will also be reviewing these aspects of your code, but if you can catch these gaps or issues up front it can speed up the process of correcting them.
- Respond to feedback. If the Committers ask questions or make suggestions for changes, please try to be responsive. The Committers are all volunteers and are trying to help as best we can, but the process moves more quickly if you can try to be responsive as well.
- Help rework/update code as needed. If suggestions for changes are made, if you can rework the code, it speeds up the process. If you submitted your code as a Pull Request, you can just quickly add changes/updates to the branch linked to from your Pull Request.
- Ask questions. If there is a long delay in the Committers responding, or if you aren't sure of the status of your contribution, please ask. We'd be glad to explain whether the delay is just because we are all busy, or if there's something else we are waiting on.
- Pay attention to release deadlines. As the next DSpace release approaches, the Committers will announce a "Contribution Deadline" for the upcoming release (usually the release schedule & deadlines are emailed to all lists in July/August). In order to keep releases on-time, the Committers must set a date after which they can no longer accept new feature contributions. Although you may add code contributions year round, they will only be considered for a specific release if they are contributed before that release's contribution deadline.
...
- For Larger Initiatives/Codebases: If you are building out a much larger project, we highly recommend notifying the community of the work early on via an email to dspace-devel@googlegroups.com (or via one of the weekly Developer Meetings). This has several benefits:
- Ensures you achieve your goals in a way that is consistent with the DSpace architecture and plans of the rest of the community.
- Minimizes the chances of a scenario where you have invested a large amount of time and effort into a body of code that does not fit in with the DSpace architecture or the consensus of the community.
- This can help find collaborators or get early feedback.
- Develop incrementally; try and implement and contribute a basic form of your feature as soon as possible, rather than aiming to implement a complete and 'polished' solution. This will help ensure you're on the right track with regards to the rest of the DSpace community and platform. The sooner your code is part of the core code base, the less time you will have to spend 'chasing' the main code base, i.e. keeping your changes up-to-date with that core code base.
- Obtain the DSpace code using GitHub (see also Development with Git). This will make code management much easier. It's very simple to do; see Developer Guidelines and Tools.
- Read 81953128 (this page) and , Code Style Guide and Code Testing Guide to ensure you are following DSpace conventions. This will ensure your code is more likely to be immediately accepted as part of out-of-the-box DSpace.
- Ensure that any third-party tools/libraries that you plan to utilize are released under compatible open source licenses. See the 81953128 Licensing of Contributions section below.
1. Make your code available (preferably in GitHub) and create a ticket in our Issue Tracker
...
| Info | ||
|---|---|---|
| ||
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 81953128 Code Contribution Standards section below. |
| Note | ||
|---|---|---|
| ||
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. |
...
| Note | ||
|---|---|---|
| ||
When we review your code, we are mostly ensuring it generally follows our 81953128. However, there are a few other things we generally check for:
|
...
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.
- Any changes must be compliant with the supported version of Java (e.g. for DSpace 7, Java 11 compliance is required)
- Your code should must adhere to our Java Code Style Guide. Most major IDEs can easily import our Checkstyle configurations to ensure alignment with this code style.
- Your code should be well commented with Javadoc (required for all classes, public methods and larger private/protected methods).
- Your code must provide unit/integration tests for new features, bug fixes or improvements per our Code Testing Guide.
- If your contribution adds new third-party tools or libraries, they must Your contribution must adhere to licensing requirements to be included. Refer to the 81953128 Licensing of Contributions below
- User interface patches changes must be internationalised (see the Internationalization Support (I18nSupport) guide)
- User interface patches must be XHTML-compliant and changes should have a W3C WCAG Conformance Level of "Double-A"Where possible, new User Interface features are encouraged to support both XMLUI and JSPUI interfaces. However, this is not a requirement. Patches supporting only one interface may be accepted.
- Your code must come with Documentation. Minimally, technical documentation must be part of the system docs – see 81953128 Documentation Contributions below. Ideally, we'd also like User/Usage Documentation.
- Examples or Use Cases should be submitted to help Committers understand and adequately test the patch prior to applying it to the core code
- Any new features should be configurable (i.e. try not to make features specific to your own institution, they need to be generalized if possible). Be careful in particular with the
dspace.cfgfile. 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 default - If you add new configuration parameters, name them appropriately. Also, they should not be required to be in dspace.cfg – if the parameters are omitted, DSpace should continue to operate as before.
- For example, if you add a new e-thesis-related submission step, you might add a couple of new config parameters:
webui.submit.thesisstep, andwebui.submit.thesisstep.color. Ifwebui.submit.thesisstep = false, the submission process should not be affected for those not using DSpace for e-theses. Also, if your code finds thatwebui.submit.thesisstepis 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 theirdspace.cfg.
- For example, if you add a new e-thesis-related submission step, you might add a couple of new config parameters:
- Add appropriate WARN, INFO and DEBUG-level logging. Use the included Apache Log4J toolkit, in concert with the
org.dspace.core.LogManagerclass to do this. Seeorg.dspace.app.webui.servlet.DSpaceServletfor an example of how to do this. - Retain backwards compatibility where possible. If there are questions/concerns about this, let us know. There are always exceptions.
- No Database schema changes unless absolutely necessary – this will mean upgrading would require effort. In this case, you also need to supply upgrade instructions and/or code to upgrade in existing installation. See 81953128 below.
- If your code makes changes to the database schema or content, and you are patching more than one branch (for example, 5_x and master), see 81953128 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.
| Note | ||
|---|---|---|
| ||
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. |
Coding Conventions
See Code Style Guide for detailed Java coding conventions and rules. The code style must be followed for Pull Requests, otherwise the automated build/test process may fail (i.e. it will throw errors related to code style violations).
...
- 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.
- Add appropriate WARN, INFO and DEBUG-level logging. Use the included Apache Log4J toolkit, in concert with the
org.apache.logging.log4j.LogManagerclass to do this.- 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)"
- Retain backwards compatibility where possible. If there are questions/concerns about this, let us know. There are always exceptions.
- No database schema changes unless absolutely necessary to support a new feature. See Database schema changes below.
- 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 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.
| Note | ||
|---|---|---|
| ||
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
...
- They must correspond to the database version and not the DSpace version.
- They are not required for DSpace to compile and run; a variety of databases, including open source databases, may be used.
Database schema changeschanges
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.
...
Overview
Content Tools