Page History

...

•  Create a ticket in the DSpace Issue Tracker (describe your contribution, how to use it, and perhaps some use cases).  This helps ensure your upcoming work is "known" to other developers, and we can let you know if someone else is working on something similar.
•  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. Please submit a GitHub Pull Request (see GitHub's "About Pull Requests"), which references your newly created ticket by number. 
  
  • If your code involves changes to the v7 REST API, please also include a REST Contract Pull Request which documents the endpoint(s) that require changes.
  • 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 / other developers 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 reviewers ask questions or make suggestions for changes, please try to be responsive. The Committers Reviewers are mostly 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 these are found in Developer Meetings notes/agendas). 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.
  

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

0. Share Early, Share Often!

The overriding mantra is share early, share often. Here are a few things to consider before you begin working on your code:

• 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 or in #dev on Slack).  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. This will make code contribution much easier, as we require a GitHub Pull Request for contributions.
• Read Code Contribution Guidelines (this page), 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 Licensing of Contributions section below.

1. Make your code available (in GitHub) and create a ticket in our Issue Tracker

Start by creating a new ticket in our GitHub Issues. 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.

Once your code is ready, you must make your code available to other DSpace Developers for review. The easiest way for us to review your code is by putting your code into a GitHub Pull Request. 

For DSpace, we follow GitHub's "Fork and Pull model" of collaborative development.  This means you should fork our DSpace GitHub repository, adding your changes to a branch in your forked repository, and then create a pull request from your fork.  In your Pull request, link back to your created issue by saying that the PR "Fixes #issue-id" (e.g. "Fixes #12345") as this will link your PR with the issue ticket.

2. Code Review Process

Once the code is made available in a Pull Request, we will work to find it reviewers/testers.  By default, every Pull Request requires at least two separate reviewers (or testers), ideally from two different institutions. Some small PRs (usually 200 lines or less) might be flagged as "1 Approval", meaning only one person needs to review that work.  During review/testing, other developers may contact you via GitHub to discuss any feedback they 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 others notice).

3. Reworking Code (if necessary) & Next Steps

After the code review & feedback, interested developers/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.

• Trade Pull Request reviews.  If your work is not getting attention as quickly as you like, it is likely all our main reviewers are busy on other PRs.  In this situation you can trade reviews on Pull Requests with another developer (preferably at a different institution). You can offer to review or test another developers PR in exchange for them reviewing/testing yours. This provides you both with immediate feedback, and Committers will often prioritize PRs which are receiving attention from others.
•  Pay attention to release deadlines. As the next DSpace release approaches, the Committers will announce a "Contribution Deadline" for the upcoming release (usually these are found in Developer Meetings notes/agendas). 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.
  

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

0. Share Early, Share Often!

The overriding mantra is share early, share often. Here are a few things to consider before you begin working on your code:

• 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 or in #dev on Slack).  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. This will make code contribution much easier, as we require a GitHub Pull Request for contributions.
• Read Code Contribution Guidelines (this page), 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 Licensing of Contributions section below.

1. Make your code available (in GitHub) and create a ticket in our Issue Tracker

Start by creating a new ticket in our GitHub Issues. 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.

Once your code is ready, you must make your code available to other DSpace Developers for review. The easiest way for us to review your code is by putting your code into a GitHub Pull Request. 

For DSpace, we follow GitHub's "Fork and Pull model" of collaborative development.  This means you should fork our DSpace GitHub repository, adding your changes to a branch in your forked repository, and then create a pull request from your fork.  In your Pull request, link back to your created issue by saying that the PR "Fixes #issue-id" (e.g. "Fixes #12345") as this will link your PR with the issue ticket.

2. Code Review Process

Once the code is made available in a Pull Request, we will work to find it reviewers/testers.  By default, every Pull Request requires at least two separate reviewers (or testers), ideally from two different institutions. Some small PRs (usually 200 lines or less) might be flagged as "1 Approval", meaning only one person needs to review that work.  During review/testing, other developers may contact you via GitHub to discuss any feedback they 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 others notice).

3. Reworking Code (if necessary) & Next Steps

After the code review & feedback, interested developers/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.

...

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 (the #dev channel in Slack or dspace-devel is best) – 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 compliant with the supported version of Java (e.g. for DSpace 7, Java 11 compliance is required)
2. Your code must adhere to our Java Code Style Guide. Most major IDEs can easily import our Checkstyle configurations to ensure alignment with this code style.
   1. Your code should be well commented with Javadoc (required for all classes, public methods and larger private/protected methods).
3. Your code must provide unit/integration tests for new features, bug fixes or improvements per our Code Testing Guide.
4. If your contribution adds REST API endpoints or changes existing endpoint(s) behavior, you must submit a corresponding REST Contract Pull Request which documents the require changes.
5. If your contribution adds new third-party tools or libraries, they must adhere to licensing requirements to be included. Refer to the Licensing of Contributions below
6. User interface changes must use i18n keys to allow for easy translation to other languages (see the DSpace 7 Translation - Internationalization (i18n) - Localization (l10n) guide). At a minimum, please provide English text so that others may translate it.
7. User interface changes should align with our User Interface Design Principles & Accessibility documentation. Primarily, this is a requirement for W3C WCAG 2.1 Conformance Level of "Double-A". 
8. Your code 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. 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.
10. Add appropriate/useful logging to your code (ERROR, WARN, INFO, DEBUG, etc).
    1. 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)"
11. Where reasonable, retain feature/functionality backwards compatibility. This does NOT mean you have to create PRs for older versions of DSpace. But, it does mean that you do your best to keep in mind the behavior of features in older DSpace releases, and attempt to keep similar behaviors where reasonable. If there are questions/concerns about this, let us know. There are always exceptions.
12. No database schema changes unless absolutely necessary to support a new feature. See Database schema changes below.
13. 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.

...

...

Our DSpace code contribution checklists are now managed in GitHub alongside the code

• User Interface (Frontend) contribution checklist: https://github.com/DSpace/dspace-angular/blob/main/CONTRIBUTING.md
• REST API (Backend) contribution checklist: https://github.com/DSpace/DSpace/blob/main/CONTRIBUTING.md

When you create a new Pull Request for DSpace, you'll also see a copy of this checklist in the pull request template.  This is for you to reference to ensure you've met our guidelines. 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.

Some additional detailed guidelines are provided below for specific scenarios:

• Licensing of Contributions - provides detailed advice for the acceptable OS licenses when you are adding new libraries/tools/plugins into DSpace.
• Database schema changes - provides detailed advice for how to update the DSpace database schema if you need to add/remove/modify database tables.
• Patching multiple branches - provides detailed advice for how to apply database changes to several branches at once (e.g. main branch and "dspace-#_x" maintenance branches) 
• Documentation Contributions - provides detailed advice on how to help with documentation for new DSpace features/improvements (or user documentation)

Licensing of Contributions

...