Page History
...
- Please be sure to share your plans with the DSpace community on the 'dspace-devel' list (or via one of the weekly Developer Meetings) before embarking on any sizable development effort. This will ensure you achieve your goals in a way that is consistent with the DSpace architecture and plans of the rest of the community. It will minimize 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.
- 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 Code Contribution Guidelines (this page) 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 Licensing of Contributions section below.
1. Make your code available (preferrably 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 (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).
...
- 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@lists.sourceforge.net. This can help find collaborators or get early feedback. We also recommend you develop your project in GitHub, as it provides easier ways to review/collaborate with other developers.
1. Make your code available (preferrably 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 (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.
| 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 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 |
| 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 Code Contribution Standards section below. |
| Info | ||
|---|---|---|
| ||
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). |
| Note | ||
|---|---|---|
| ||
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. |
...
- Any changes must be Java 1.6 compliant.
- When possible, your contribution should be a "Pull Request" sent to our GitHub repository (see Development with Git). However, you may also create a patch against the latest version of the code (but submitting a patch may delay the review process, as we will need to locate a volunteer to create a Pull Request on your behalf).
- Any patches submitted should be small diffs (no large all encompassing patches!) using the unified output format. If you need help with generating a patch, there are many good resources out on the web. Here are just a few:
- Any patches submitted should be small diffs (no large all encompassing patches!) using the unified output format. If you need help with generating a patch, there are many good resources out on the web. Here are just a few:
- Ensure the code is commented and correctly formatted (you can use many IDE's format functions to do that or a tool like Jacobe ). Refer to the Coding Conventions section below.
- Your contribution must adhere to licensing requirements to be included. Refer to the Licensing of Contributions below
- User interface patches must be internationalised (see the I18nSupport guide)
- User interface patches must be XHTML-compliant and have a W3C WAI 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 patch must come with Documentation. Minimally, technical documentation must be part of the system docs – see 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 requiredto 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 Database schema changes below
...
Overview
Content Tools