High Level Guidelines

1. Be consistent
2. Don't rewrite existing code just to follow these guidelines
3. Refactoring should be kept separate from functional updates, to make it easier to review.
4. Smaller updates are better and much easier to review. It's OK to submit a chain of small updates that build off each other.
5. Don't violate a guideline without good reason. If you do, expect to be asked to defend the reasoning.
6. A reason is good when you can convince another core committer and the violated guideline should be reviewed if it needs to be changed.

Committing Guidelines and Flow

1. Find or create a bug report or feature request ticket in JIRA 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. Assign the ticket to yourself prior to starting the work so that others in the community know that you have taken responsibility for implementing the solution.
2. Set up a GitHub account if you have not done so before.
3. Fork the ArchivesSpace repository on GitHub. The advantage of forking existing codebases is that you can do so without asking anyone and get started quickly. The disadvantage is that there's a risk of writing code that only lives in your fork, which – if you wind up running this in production, or pointing other production code at your fork – is a surefire way to make your work difficult to upgrade.
4. Create a feature branch. Do not work directly on the master branch, which is a protected branch. It is helpful to start the name of the branch with the JIRA ticket or Github issue number.
5. As you start working on your contribution, feel free to make commits as often as makes sense to you since no one will see these until you push your code up to GitHub; there will be an opportunity later to squash your commits and make sure your commit message is written succinctly and with sufficient detail. (Your commit message will be pulled in as the default description of your PR, so investing some time in writing a high-quality commit message will help you, and code reviewers, later.)
6. We also recommend writing tests early and running them often, making small commits as you go. This gives you frequent checkpoints to make sure you do not dig yourself into a deep hole or become bogged down towards the end of working on your changes.
7. Make changes in your fork. We advise contributors to follow these guidelines to expedite the contribution review process.
   1. Include the JIRA ticket or Github Issue number in your commit message.
   2. 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/+
   3. Include unit tests sufficient to cover the feature(s) you add or bug(s) you fix, and make sure the test suite passes when you run it locally.

1. 1. Make sure the code is
      1. stable and has no stability or security concerns
      2. properly using existing APIs, etc.
      3. not too specific to one institution's local policies or workflows. 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.
   2. Any third-party tools/libraries used by your code have compatible open source licenses.
   3. If you're adding a feature or otherwise changing documented behavior, modify the documentation to reflect your changes.
2. Once your work is done, squash the commits in your branch — see One Commit per Pull Request for some guidelines — and rebase it to the latest in the upstream master branch. We appreciate succinct but explanatory commit messages – see A Note About Git Commit Messages.
3. Push your updated branch to your fork.
4. Create a Pull Request on GitHub. We have found that it is best when pull requests are small; targeted at a specific issue; and pushed up quickly for review.
5. Respond to feedback as the community reviews your contribution.

When Submitting a Pull Request

When you have code ready to be reviewed, and it meets the Code Contribution Guidelines, open a pull request to ask for it to be merged into the codebase.
To help make the review go smoothly, here are some general guidelines:

• Your pull request should address a single issue.
  • It's better to split large or complicated PRs into discrete steps if possible. This makes review more manageable and reduces the risk of conflicts with other changes.
• Give your pull request a brief title, and use the description to provide key information:
  • Provide a list of the key changes
  • If your PR addresses an existing GitHub ticket, link to it with "Fixes #123". This will make it easy to refer back to the original ticket and automatically close it when the PR is merged.
  • If your PR addresses an existing JIRA ticket, include a link in the description to the corresponding JIRA ticket.
  • If you've discussed the issue, or just want to alert someone to your PR, tag them by including their @username.
  • Link to relevant resources, such as Wiki pages, mailing list threads, specifications, or other tickets. This makes it easier to understand the full context of your PR.
• Please be patient. Your PR may not be reviewed right away, since the people doing code review are often busy, and may be traveling, in a different time zone, or otherwise not available to review your code immediately.
  • It is fine to ask someone to review, either by tagging them in a comment or asking on the core committers' mailing list, especially if it is blocking other work.
• Respond to code review comments, with discussion where it's appropriate or by pushing additional commits to the branch. They will be added to the same PR automatically.
• If another PR is merged and conflicts with your changes, you may need to rebase your PR.
  • See GitHub's rebasing documentation and One Commit Per Pull Request for more information on rebasing.