Page History

...

1. Any changes must be Java 1.7 compliant.
2. 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:
     
     • How to Create a Patch
     • Creating Patchs
     • Ten Minute Guide to Diff and Patch
3. 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.
4. Your contribution must adhere to licensing requirements to be included. Refer to the Licensing of Contributions below
5. User interface patches must be internationalised (see the Internationalization Support (I18nSupport) guide)
6. User interface patches must be XHTML-compliant and have a W3C WAI Conformance Level of "Double-A"
7. 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.
8. 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.
9. Examples or Use Cases should be submitted to help Committers understand and adequately test the patch prior to applying it to the core code
10. 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.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
11. 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.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.
12. 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.
13. Retain backwards compatibility where possible. If there are questions/concerns about this, let us know. There are always exceptions.
14. 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.
15. If your patch makes changes to the database schema or content, and you are patching more than one branch (for example, 5_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.

...

• For Database migrations/management, we use FlywayDB
  • The migration scripts are available in the dspace-api source code under the org.dspace.storage.rdbms.sqlmigration package: https://github.com/DSpace/DSpace/tree/master/dspace-api/src/main/resources/org/dspace/storage/rdbms/sqlmigration
  • Each new migration script should be named "V[version]_[date]__[description].sql", where [version] is the DSpace version supporting this change, [date] is the date of the change, and [description] includes the associated ticket number and brief description of the migration. For example: "V5.0_2014.09.26__DS-1582_Metadata_For_All_Objects.sql".
• If your database migration adds new sequences, then you should also be sure to update the update-sequences script at:
  • [dspace-src]/dspace/etc/[db-type]/update-sequences.sql
  • At this time, this updated-sequences script is maintained outside of the database migrations as it is useful to run manually after large restorations, etc.

Patching multiple branches

Anchor
Patching multiple branches 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.

• FlywayDB migrations are cumulative.  You should depend on changes that you made in the earliest affected branch to be available in later branches, and only do further migrations in later branches if additional changes are needed.
• When patching a branch earlier than 5_x, you will need to provide an SQL script or a tool to be run manually.  5_x and later patches should still depend on these manual updates, and you should document the need to run them before allowing automatic migrations to run.
• If the schema was already changed between branches, and those changes affect the same tables that you are updating, depend also on the existing upgrade process to make those changes for you.  For example:  if you make database changes to table T in branch X, and the upgrade from X to Y changes the schema for T, you don't need to rewrite your changes for branch Y because the upgrade already took care of that difference.

Documentation Contributions

...