Skip to end of metadata
Go to start of metadata

Introduction

CollectionSpace welcomes contributions from our community.  Some examples of community contributions include:

  • Source code additions or modifications, in Java (Application and UI layers) or JavaScript (UI layer)
    • Example: adding new procedures
    • Example: adding new capabilities to the user interface
  • Schema extensions
    • Example: adding a community of practice schema (a schema within a specific domain, like art history or life sciences)
  • Modifications to HTML templates and CSS stylesheets
  • Configuration additions or modifications, such as changes to configuration files in any of CollectionSpace's layers
  • Data import tools, including ETL templates and import scripts
  • Data cleanup scripts
  • Utility scripts
  • Lists of authority terms
  • Lists of vocabulary terms
  • Translations into different languages (e.g. translated 'message bundle' files for localizing text labels)
  • Documentation
  • Notes on best practices
  • Wireframes (drawings of one or more screen layouts, as a user might interact with them)

The impact ratings listed below give you an idea of how we assess the impact of external code on the CollectionSpace code base.  The impact assessment determines the approach that the core team will take with regard to integrating external code into the 'core' code. We urge you to consider the impact ratings listed below before you begin development of any code that might be contributed back to CollectionSpace.

Different Code has a different impact on the CollectionSpace code base

Green Level

Extension can be represented/implemented in overlays and configuration (no code addition, only requires schemas, config, css, html, etc. No recompiling necessary). Can easily model overlays in the code repository (and in the demo site) if we model  multi-tenancy. Note that even this level requires maintenance.

This is the easiest to develop and deliver, and requires minimal interaction with the CollectionSpace team.

Amber Level

Extension must add something to the code, extend the core services, create a service. To fit in this category, the extension must not alter existing functionality (how current code works, and especially how existing services work). Incorporating such an extension creates a moderate burden, esp. if we are heavily multi-tenanted. These extensions would need a little more scrutiny, and especially financial scrutiny (for supporting and maintaining).

At this level, it is likely that the contributor will need to engage with the CollectionSpace team to develop a successful extension.

Red Level

Extension involves more complicated changes, changing existing core code, and may even introduce risk of a code branch (because of divergent service contracts or functionality). We would need a really good justification to accept such an extension into the code repository.

The contributor will need to work with the CollectionSpace team before they even start.

Getting Started

A set of workflows, checklists, and related support documents (such as a schema template) have been developed to assist with the code contribution process.  Follow the workflow for the type of code that you would like to contribute. 

If someone contributes, are we bound to support it?

There are differing levels of contribution - overlays on the application all the way down to core changes to how it works. If a contributor can manage to do things as an extra service/overlay, we can accommodate. If you're proposing something that will be a branch, that will require a lot more scrutiny.

Three cases

  • Things that don't require recompiling and don't touch our code, doesn't break our tests. This scenario is low cost to us, high benefit, and low risk.
  • If new code will require compilation and is an extension of code – like adding a new procedure - it has high benefit with low cost. Shouldn't have to change other things in the system to accommodate the contribution. This makes it low risk. We will need to scrutinize these contributions; we will need to create some standards that they will have to follow. We could create a contributions directory and the community could try out these types of contributions.
  • If a contributor wants to add GIS search, or different audit model, this represents a difficult, fundamental difference from the CollectionSpace Code Base, and could lead to fork in the code. We would need to assess the cost/benefit to other implementers. We could not leave something like this in the Contributions directory for members of the community to try out.

We need to determine how beneficial the contributed code is to the community for all levels. We will upgrade contributions along with CollectionSpace that have great value to the community as a whole. There will be some contributions that we determine do not have that general applicability that we do not maintain going forward, and they could become obsolete as CollectionSpace moves forward. It will depend on the contributor's willingness to maintain it.

At some point we will want some more guidelines around if you're going to do an authority, you have to follow our model for authorities unless you can make a strong argument for reinventing the wheel. Don't rebuilt a new kind of record, if an existing one would have done the job. Just because you didn't understand it, doesn't mean you needed to rewrite it.

Reference: How other projects manage Contributing Code

Sakai created a quality council – They have a process where the council voted, thought about how much it would cost maintenance-wise, how broad would the interest be across institutions, how good is the documentation; then if it passed these criteria they agreed to accept it into the core. The criteria were public, so you had an idea when you started whether your contribution would make it into the core. There was a process of election onto the council, reasonably formalized. We can't force anyone to contribute. We want to think about the motivation model so we get contributions that are valuable to the whole community.

Sakai Development Process
Sakai Product Council

For Infusion, there is product management involved. The people who would make the final decision are Justin and Colin, based upon what the community feels in general. In Infusion the components are graded (production, sneak peek, preview) so if they got something from someone that they thought could be useful, they might ship with the product with a sneak peek form. Wouldn’t ship if it didn't have tests and didn't have a certain amount of QA. Sneak peek has different expectations – production, for example, requires a stable API. Also have an incubator in the SVN. People who want to be in the community but not in the product can have commit access to the incubator.

Fluid Coding and Commit Standards

Nuxeo has an extended description of their commit process, with clearly delineated steps: Contributing to Nuxeo

OpenCast:Matterhorn Project Governance Diagram

OpenCast: Committers and Contributors

DSpace: Committer Guidelines

Fedora: Committer's Guide