Page History
...
This page has a lot of great information on it. But, if you just need the high level overview, here it is. NOTE: the checkboxes below are here for "decorative" purposes, and aren't really intended to be used. If you'd like, and you find it helpful, you may print this page and then check off each step as you proceed with your contribution. Happy coding, and please ask for help if you find you need it! We are a community of developers, and we love to help.
- Create a ticket in the DSpace Issue Tracker (describe your contribution, how to use it, and perhaps some use cases). Submit your code (preferably via GitHub). It is HIGHLY recommended to do so via a GitHub Pull Request (see 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.
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
- Write unit/integration tests per our Code Testing Guide
- 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 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.
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:
- 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.
- 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.
Info | ||
---|---|---|
| ||
Oh, please. Think of it like this: open source software development is like a conversation. The conversation has to start somehow. Here's what you can do right now: create a JIRA issue, explaining your idea, and make a new branch, using that issue number in the branch name. Now, commit your new code to that branch, and push it up to your fork on GitHub. Now, the conversation has already started, and people have a way to discuss your idea in a meaningful fashion–referring to the JIRA issue number, perhaps reviewing and commenting on your branch on GitHub. It would probably be a good idea to link to your work in progress branch from the JIRA issue, as it will make finding you work, and the process of reviewing it, easier. Before you know it, you'll be ready to make a pull request, and your work will already have champions within the DSpace community, all because you put it out there and made it available for review early. Sounds like fun, doesn't it? That's because it is fun. Come, join the conversation! |
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). However, please be aware that submitting a patch may delay the review process (see below note)
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. |
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. |
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 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).
Info | ||
---|---|---|
| ||
The timeframe of a code review will vary, based on how much time the Committers have. Smaller changes may be reviewed within days, while larger changes/features may take many weeks to do a full review. All Committers are volunteers and only have a small amount of time to provide to the project in a given week. We will make every effort to get back to you with feedback within a few weeks. But, if you haven't heard anything, feel free to ask! |
Note | ||
---|---|---|
| ||
When we review your code, we are mostly ensuring it generally follows our Code Contribution Standards. However, there are a few other things we generally check for:
|
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.
Info | ||
---|---|---|
| ||
As our Committers are all volunteers, they don't always have the time to rework code changes for you. If you want your code change accepted in a timely manner, please offer to make the changes yourself (otherwise your patch suggestion may wait in a "holding queue" until someone has enough time to work on any necessary fixes). |
Note | ||
---|---|---|
| ||
If you are unsure of next steps, please let us know by adding a comment to your issue in the Issue Tracker. Communication is absolutely necessary to ensure that we can help you rework anything that needs reworking. If we don't hear from you, we'll assume you are hard at work. So, if you've run into issues, please let us know! If, locally, you don't have the time or expertise to do the rework that is necessary, also let us know. We can try to locate a community developer to help out, and/or ask both the Committers Team and the DSpace Community Advisory Team if they know of any interested developers with time to spare. |
4. Acceptance!
Once your code is accepted, it will be released in the next version of DSpace software! It is time to celebrate, as your name will be added to the prestigious list of DSpace Contributors!
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.
- Any changes must be Java 1.7 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 Internationalization Support (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.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
, 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.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 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.LogManager
class to do this. Seeorg.dspace.app.webui.servlet.DSpaceServlet
for 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
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.
Note | ||
---|---|---|
| ||
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
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 Licensing of Contributions below). Also take a look at 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). All code contributions must come with Documentation. 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
Any third-party libraries (e.g. JARs / Maven Dependencies) required to compile or run DSpace must be included. The license of any required jar/dependency 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 acceptable to require additional downloads of JARs/dependencies to make DSpace compile or function.
Non-Java third-party web frameworks or tools (e.g. XSLT, CSS, Images) should follow these same licensing guidelines.
Examples of acceptable licenses:
- Apache License 2.0
- BSD
- Common Development and Distribution License (CDDL)
- Common Public License (CPL)
- GNU Library or "Lesser" General Public License (LGPL)
- MIT / X11 License
- Mozilla Public License
- Additional examples may be found in our LICENSES_THIRD_PARTY file in the source code. This file lists the licenses of all third-party libraries used by DSpace.
Examples of unacceptable licenses:
- GNU General Public License (GPL)
- GNU Affero General Public License (AGPL)
- European Union Public Licence (EUPL)
- Similar to GPL, this license is "share alike" / "strong copyleft" and may require usage of the same license for redistribution or derivatives. For more information, see the EUPL FAQ (specifically the questions "What about compatibility issues?" and "Are there limitations to the use of the software?")
- Any license which strictly forbids "sublicensing" as detailed at http://choosealicense.com/licenses/
- Any license which limits commercial use/redistribution of binary code
Note | |||||
---|---|---|---|---|---|
| |||||
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:
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:
|
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.
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 files with your sequences, tables, views etc. (in /dspace/etc/postgresql, /dspace/etc/oracle, and /dspace/etc/h2):
- 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.
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 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. These development release timelines are usually found in Developer Meetings notes/agendas. |
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).
Info | ||
---|---|---|
| ||
The timeframe of a code review will vary, based on how much time the core developers have. Smaller changes may be reviewed within days, while larger changes/features may take many weeks to do a full review. All Developers/Committers are volunteers and only have a small amount of time to provide to the project in a given week. We will make every effort to get back to you with feedback within a few weeks. But, if you haven't heard anything, feel free to ask! |
Note | ||
---|---|---|
| ||
When we review your code, we are mostly ensuring it generally follows our code contribution checklists for the frontend or backend (depending on the type of PR):
If you skip any guidelines in that checklist, you will be asked to update your code, or it may be delayed/rejected. |
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.
Note | ||
---|---|---|
| ||
If you are unsure of next steps, please let us know by adding a comment to your issue/PR in GitHub. Communication is absolutely necessary to ensure that we can help you rework anything that needs reworking. If we don't hear from you, we'll assume you are hard at work. So, if you've run into issues, please let us know! If, locally, you don't have the time or expertise to do the rework that is necessary, also let us know. We can try to locate a community developer to help out, and/or ask both the Committers Team and the DSpace Community Advisory Team if they know of any interested developers with time to spare. |
4. Acceptance!
Once your code is accepted, it will be released in the next version of DSpace software! Your name will appear in the Release Notes as a contributor to that release!
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 (the #dev channel in Slack or dspace-devel is best) – we'll be glad to explain or help.
Contribution Checklist
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
Any third-party libraries (e.g. JARs / Maven Dependencies) required to compile or run DSpace must be included. The license of any required jar/dependency 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 acceptable to require additional downloads of JARs/dependencies to make DSpace compile or function.
Non-Java third-party web frameworks or tools (e.g. XSLT, CSS, Images) should follow these same licensing guidelines.
Examples of acceptable licenses:
- Apache License 2.0
- BSD
- Common Development and Distribution License (CDDL)
- Common Public License (CPL)
- GNU Library or "Lesser" General Public License (LGPL)
- MIT / X11 License
- Mozilla Public License
- Additional examples may be found in our LICENSES_THIRD_PARTY file in the source code. This file lists the licenses of all third-party libraries used by DSpace.
Examples of unacceptable licenses:
- GNU General Public License (GPL)
- GNU Affero General Public License (AGPL)
- European Union Public Licence (EUPL)
- Similar to GPL, this license is "share alike" / "strong copyleft" and may require usage of the same license for redistribution or derivatives. For more information, see the EUPL FAQ (specifically the questions "What about compatibility issues?" and "Are there limitations to the use of the software?")
- Any license which requires "same license" (i.e. strong copyleft) as detailed at http://choosealicense.com/licenses/
- Any license which limits commercial use/redistribution of binary code
Note | |||||
---|---|---|---|---|---|
| |||||
DSpace 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:
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:
While DSpace is released under BSD licensing, the same issues exist between BSD licenses and GPL-based licenses. |
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.
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.
- For Database migrations/management, we use FlywayDB
- The migration scripts are available in the
dspace-api
source code under theorg.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".
- NOTE: Whenever possible, please avoid modifying migration scripts from a prior DSpace release. Flyway does not compare modified scripts against the current database structure, so it will not modify tables based on modifications to existing migration scripts. Therefore, modifications to existing scripts may result in some (or all) DSpace users having to manually run those database changes during their next upgrade.
- Instead, where possible, consider creating a migration script (in SQL or Java) that will run just before (or after) the script you are looking to modify.
- The migration scripts are available in the
- 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 | ||||
---|---|---|---|---|
|
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.
- 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
All new features require documentation before they will be accepted. You may send us code before documentation is completed, but we will be unable to accept that code into DSpace until it is properly documented. Bug fixes may not require documentation, unless they somehow make a modification which changes how DSpace functions.
As of 1.7.0, the All documentation is now built in a special section of the Wiki at DSpace Documentation. Therefore, the best way to send us Documentation is to actually create a new page(s) in this DSpace Wiki. You should link these Wiki page(s) to your issue in our DSpace Issue Tracker. We'll move them over into the official DSpace Documentation area once you code has been accepted.