Versions Compared

Old Version 25

changes.mady.by.user Unknown User (jamesenglish)

Saved on

compared with

New Version 26

changes.mady.by.user Unknown User (jamesenglish)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  •  Create a ticket in the Issue Tracker (describe your contribution, how to use it, and perhaps some use cases).
  •  Make sure your code adheres to our 
  •  Submit your code (preferably 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.
  •  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.

...

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

...

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.

  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).
  3. Your code should adhere to our Java Code Style Guide.  Most major IDEs can easily import our Checkstyle configurations to ensure alignment with this code style
  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 WCAG 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.

Attempt to Follow all Guidelines

 

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.

Coding Conventions

Coding Conventions

See guidel bellow for convenstions 

The code must be tagged as 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)not execute.

Your code should be well commented with Javadoc (including package and class overviews). All code contributions must come with DocumentationTest Coverage. At a bare minimum, this should include Technical Documentation covering all configuration options and/or setup. See Documentation Contributions below for more details. 

Licensing of Contributions

...

Examples of unacceptable licenses:

Why is GPL (and similar) unacceptable?

 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:

similar) unacceptable?

In addition, the Apache Software Foundation has a good explanation of why they are also forced to avoid GPL-based (copyleft) licenses because of its one-way compatibility with Apache License 2.0:

"This licensing incompatibility applies only when some Apache project software becomes a derivative work of some GPLv3 software, because then the Apache software would have to be distributed under GPLv3. 

We avoid GPLv3 software because merely linking to it is considered by the GPLv3 authors to create a derivative work. We want to honor their license. Unless GPLv3 licensors relax this interpretation of their own license regarding linking, our licensing philosophies are fundamentally incompatible. This is an identical issue for both GPLv2 and GPLv3."

 

While

DSpace

SimplyE is released under

BSD

Apache licensing, the same issues exist between BSD licenses and GPL-based licenses

.

JDBC drivers for databases are an exception since:

...

.

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

...