Contributing to ArchivesSpace

Reporting Bugs

  1. Always update to the most recent master release; the bug may already be resolved.

  2. Search for similar issues in Pivotal Tracker -- it may already be an identified problem.

  3. If this is a bug or problem that requires any kind of extended discussion, post to the mailing list first.

  4. If this is a bug or problem that is clear, simple, and is unlikely to require extended discussion -- open an issue in Pivotal Tracker including steps to reproduce the bug, error messages, screenshots, URLs, etc.

  5. If possible, submit a Pull Request with a failing test. If you'd rather take matters into your own hands, fix the bug yourself (jump down to the "Contributing Code" section).

  6. When the bug is fixed, we will do our best to update the GitHub issue with a resolution.

Requesting Improvements

  1. Feature requests can be made via Pivotal Tracker or the mailing list.

  2. Search Pivotal for similar feature requests. It's possible somebody has already asked for this feature or provided a pull request that we're still discussing.

  3. Provide a clear and detailed explanation of the feature you want and why it's important to add. The feature must apply to a wide array of users.

  4. For smaller, more targeted "one-off" features, you might consider writing a plugin for ArchivesSpace. You may also want to provide us with some advance documentation on the feature, which will help the community to better understand where it will fit.

Contributing Code

  1. Make sure that you have completed an Individual Contributor License Agreement, or that your institution has completed an Corporate Contributor License Agreement. (NOTE: this is not strictly necessary, though it is recommended, for contributions to ArchivesSpace Labs code repositories.)

  2. Find or create a bug report or feature request ticket in Pivotal Tracker or GitHub (to make sure you’re not duplicating work and document the intent of your contribution). It helps to explain both the existing behavior and the desired behavior that your change will implement.

  3. Set up a GitHub account if you have not done so before.

  4. Fork the ArchivesSpace repository on GitHub.

  5. Create a feature branch.

  6. Make changes in your fork. We advise contributors to follow these guidelines to expedite the contribution review process.

    1. Follow established style guidelines

      1. Rails: https://github.com/bbatsov/rails-style-guide

      2. JRuby: https://github.com/jruby/jruby/wiki/JRubyStyleGuide

      3. RSpec: http://betterspecs.org/

    2. Include unit tests sufficient to cover the feature(s) you add or bug(s) you fix, and make sure the test suite passes. (Can we rely upon Travis or a Jenkins instance for this, or should we suggest that contributors run tests locally?)

    3. If you’re adding a feature or otherwise changing documented behavior, modify the documentation to reflect your changes.

  7. Once your work is done, squash the commits in your branch — see One Commit per Pull Request for some guidelines — and rebase it on the latest in the upstream master branch. We appreciate succinct but explanatory commit messages.

  8. Push your updated branch to your fork.

  9. Create a Pull Request on GitHub.

  10. Respond to feedback as the community reviews your contribution.

Developer Resources