Contribution Quick Checklist

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 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 GitHub's "About Pull Requests", or our notes on Development with Git), which references your newly created ticket by number (e.g. SIMPLY-1234). 
    Mobile Git Guide Lines
  • 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.

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

1. 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 Library Simplified community on the slack (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 SimplyE 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 SimplyE 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 theLibrary Simplified community and SimplyE 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 SimplyE 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 for Mobile Developers if developing on the Mobile Apps
  • Ensure that any third-party tools/libraries that you plan to utilize are released under compatible open source licenses. See the Code Contribution Guidelines#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 info@librarysimplified.org. 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.


My Code is NOT ready.

But, my code's not ready!

Don't worry! 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.

Make your code available (preferably in Github)

Once your code is ready, you must make your code available to the SimplyE 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 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 Issue Tracker. This ensures that the SimplyE Developers are notified of your contribution, and acts as a place for us to comment on the work or make suggestions for improvements.

Code Standards

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.

To ensure your contribution is reviewed more quickly, send us a GitHub Pull Request!

To ensure your contribution is reviewed more quickly, send us a GitHub Pull Request!

When making a code contribution, at the very least you should create a new ticket in our 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).


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

Code Review Timeframe

 

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!

What are we reviewing for?

 

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:

  • The code is stable and has no stability or security concerns
  • The code is properly using existing APIs, etc.
  • The code is not too specific to one institution's local policies or workflows. (I.e. we will review the code to ensure it looks to be generally useful to most institutions, or configurable enough such that others can change it to match their own local policies/workflows)
  • Any third-party tools/libraries used by your code have compatible open source licenses. See Licensing of Contributions

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 SimplyE. If it can be accepted immediately, it will be. If not, we'll try to help figure out the best route forward.

How you can help speed up the process

 

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

Communicate, Communicate, Communicate

 

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

Coding Conventions

See guidel bellow for convenstions 

The code must be tagged as Pull Requests, otherwise the automated build/test process may not execute.

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

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:

Examples of unacceptable licenses:

Why is GPL (and 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 SimplyE is released under Apache licensing, the same issues exist between BSD licenses and GPL-based licenses.

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

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 SimplyE until it is properly documented. Bug fixes may not require documentation, unless they somehow make a modification which changes how SimplyE functions.

  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.