See also the Guide to Developing with DSpace.

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

1. Make your code available

First, you must make your code available to the DSpace Committers Group for review. This can be in the form of a patch (usually posted to our DSpace Issue Tracking System). Alternatively, you may provide us with downloadable version or read-only access to your SVN or CVS code repository.

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 code changes are readily accepted (because they are stable and look good), others may require more work (if there are concerns or issues that Committers notice).

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.

4. Acceptance!

Once your code is accepted, it will be released in the next version of DSpace software!

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.

• When possible, your contribution should be a patch against the SVN Trunk.
• Ensure the code is commented and correctly formatted (you can use Eclipse's format function 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"
• Technical and User on-line help as part of the patch. Technical documentation must be part of the system docs – see Documentation Contributions below.
• Examples or Use Cases should be submitted to help Committers understand and adequately test the patch prior to applying it to the core code
• Patches should be small diffs (no large all encompassing patches!) using the unified output format (see Submitting a Patch below for flags)
• Any new features should be configurable. Be careful in particular with the `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 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, and webui.submit.thesisstep.colour. 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.
• Add appropriate WARN, INFO and DEBUG-level logging. Use the included Apache Log4J toolkit, in concert with the `org.dspace.core.LogManager` class to do this. See `org.dspace.app.webui.servlet.DSpaceServlet` for an example of how to do this.
• Retain backwards compatibility where possible
• No DBMS 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
• Any changes must be Java 1.6 compliant.

Coding Conventions

Your code needs to follow the Sun Java code conventions with the following minor modifications:

• Curly braces must be on new lines.
• Source files must have a copy of the copyright Duraspace notice and BSD license at the top (see below) - see also Copyright and Licensing.
• You must use 4-space tabulation.
• 'else' should be on a new line. 'else if' stays on one line.
• Users of the Eclipse IDE can have eclipse do the formatting automatically using this profile: - dspace-eclipse-format.xml. See the Eclipse section below for details of how to apply this profile.

Your code should be well commented with Javadoc (including package and class overviews). You should also be prepared to document your code in the system docs, but you don't need to do that before contributing the code.

Licensing of Contributions

Any third-party libraries (JARs) required to compile or run DSpace must be included. The license of any required jar 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 acceptible to require additional downloads of JARs to make DSpace compile or function.

Examples of acceptable licenses:

• BSD
• Apache License
• GNU Library or "Lesser" General Public License (LGPL)

Examples of unacceptable licenses:

• GNU General Public License (GPL)
• Any license which limits commercial use/redistribution of binary code

JDBC drivers for databases are an exception since:

• 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.

If you are including new jars or later versions of existing jars, you need to include the associated license file for inclusion in the lib/license directory. The README file in the lib directory must also be updated as part of the patch to describe the jar and identify the jar version.

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.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):

• database_schema.sql - the SQL to create the database from scratch
• clean-database.sql - the SQL to remove all the parts of the database
• database_schema_<old version>-<new version>.sql (e.g. database_schema_11_12.sql) - the SQL to update the <old version> of the schema to the <new version>
• update-sequences.sql - the SQL to ensure that sequences are set correctly

Documentation Contributions

Follow exactly the same procedure as above; the documentation resides in the {dspace/docs/docbook} directory.

As of 1.5.1, the documentation is now in docbook. The docbook sources are used to
generate both HTML and PDF forms of the documentation. There are many docbook tutorials available, but you may find it easiest to just review the existing documentation source for an example of what you want to achieve.