Community Contributions Process - DRAFT

This is a rough, early draft of the CollectionSpace Community Contribution process: the process by which CollectionSpace community members can contribute work that advances the core project, customizes it for use in various domains, and the like.

Examples of community contributions

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, such as rights management, condition checking, valuation
  • Example: adding new capabilities to the user interface, such as the ability to display text addresses or lat/long pairs on a map, or to validate data entry against external web services
• Schema extensions
  • Example: adding new fields widely used within a specific domain, like art history or the life sciences, to existing object or procedural records
• 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)

Getting started

If you wish to contribute code, the place to start is with an announcement or query on the project's Talk list. This way, you can elicit feedback and interest from others in the community, as well as identifying whether others may be working on similar contributions.

The mechanics of contributing

CollectionSpace has recently moved its source code into public repositories on GitHub. There are git repositories there for each of CollectionSpace's three layers:

• application
• services
• ui

For most code and configuration contributions you may wish to make, we encourage you to use GitHub to fork ('clone') these repositories, and then use git to create a local feature branch containing your changes, in each relevant layer. The project's developers will then create corresponding feature branches in the relevant layers in the main CollectionSpace repository, to which you can issue pull requests. When contributions are approved, the changes in the feature branches will be merged into the corresponding master branches, then the feature branches will be retired (removed).

If you have made your configuration changes in the CollectionSpace mini-build, you can first copy your added or changed files from the mini-build into your local feature branches for the relevant layer(s). (A future version of the mini-build may offer tools to make this more convenient.)

If you are contributing files that don't have an obvious home within the CollectionSpace source code trees, such as import scripts, vocabulary term lists, documentation, or wireframes, you can make these available in any convenient manner, such as on your own website, on a file transfer site, or in your own git or Subversion repository.

The most useful contributions, which are most likely to be accepted into the project, or alternately, to be most easily adopted by other institutions within the community, are contributions limited to a single distinct feature, such as a new procedure, a new user interface function, or new and improved method of importing data.

A mix of multiple customizations for your museum, while useful in its own right as an example, capable of spurring inspiration and ideas - and thus itself entirely worthy of being shared - may be more difficult to incorporate into the project and more challenging to be adopted outright by others.

Metadata around contributions

Your contributions should include some minimal metadata, including:

• A brief description of the contribution
• The relevant institution(s) from which the contribution comes, if any
• A contact person
• The CollectionSpace version(s) against which the contribution was tested

In addition, if relevant:

• Listings of any system requirements, prerequisites, dependencies, etc.
• Pointers to any special installation and/or usage instructions

The CollectionSpace project will provide a mechanism for aggregating and/or linking to metadata for each community contribution.

Reviewing code for acceptance

There will be a process established for reviewing contributions that are intended for CollectionSpace's core code and configuration.

Functional analysts and core project developers for each of the relevant CollectionSpace layers will participate in this process. As one representative example, contributions may be reviewed to ensure that they provide the requisite automated tests, where relevant.

In some cases, the contributed code may be hosted on a server - whether the contributor's or the project's - so that it can be viewed 'live.'

As a general rule, because of the limited resources on the core development team, the project is seeking to "own" as little code as possible. Features developed by community members that are also on the project's short- or long-term roadmap have a higher likelihood of adoption. Community contributions, maintained by outside contributors, that can be readily "plugged in" to one or more releases of the CollectionSpace system are also extremely welcome.