Home

Welcome to Arches - an open-source, geospatially-enabled software platform for cultural heritage inventory and management, developed jointly by the Getty Conservation Institute and World Monuments Fund. The system is freely available for organizations worldwide to download, install, and configure in accordance with their individual needs and without restrictions.

This wiki is the main source of documentation for developers working with (or contributing to) the Arches project. If this is your first time hearing about Arches, we recommend starting with the Arches Project website. You can also check out the full user documentation for v4, a manual for installation and configuration of the app for the non-developer crowd.

Contributing to Arches

We'd love for you to contribute your time, experience or knowledge to help make Arches even better than it is today! Here are the guidelines we'd like you to follow:

• Question or Problem?
• Issues and Bugs
• Submission Guidelines
• Commit Message Guidelines
• Additional Notes

Got a Question or Problem?

If you have questions about how to use Arches, please direct these to the Google Group discussion list.

Found an Issue?

If you find a bug in the source code or a mistake in the documentation, you can help us by submitting an issue to this GitHub Repository. Even better you can submit a Pull Request with a fix.

Submitting an Issue

Before you submit your issue search the archive, maybe your question was already answered.

If your issue appears to be a bug, and hasn't been reported, open a new issue. Please add the appropriate labels to the issue (multiple labels are ok) to help us keep track of them. Most labels are used across all Arches Project repositories, but some are specific to archesproject/arches.

[LIST OF LABELS HERE!!!]

Creating a Bug Fix/Enhancement Branch

Typically, work on arches is done in branches outside of master, and then merged into master when all work on that bug/feature is completed. Branches are usually created to resolve a particular ticket. As such, branches are typically named for the ticket number they address followed by a short description of the issue addressed in the ticket, all in snake case.

For Example: If I am working on ticket "1231 Cool New Feature" my branch may be named 1231_cool_new_feature

Submitting a Pull Request

• Make your changes in a new git branch:

  git checkout -b my-fix-branch master

• Commit your changes using a descriptive commit message that follows our commit message conventions:

  git commit -a

  Note: the optional commit -a command line option will automatically "add" and "rm" edited files.

• Test your changes locally to ensure all the tests pass:

  INSERT COMMAND HERE

• Push your branch to GitHub:

  git push origin my-fix-branch

• In GitHub, send a pull request to arches:master.

• If we suggest changes then:

  • Make the required updates.
  • Re-run the test suite to ensure tests are still passing.
  • Commit your changes to your branch (e.g. my-fix-branch).
  • Push the changes to your GitHub repository (this will update your Pull Request).

• If the PR gets too outdated we may ask you to rebase and force push to update the PR:

  git rebase master -i
  git push origin my-fix-branch -f

WARNING. Squashing or reverting commits and forced push thereafter may remove GitHub comments on code that were previously made by you and others in your commits.

That's it! Thank you for your contribution!

After your pull request is merged

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository:

• Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

  git push origin --delete my-fix-branch

• Check out the master branch:

  git checkout master -f

• Delete the local branch:

  git branch -D my-fix-branch

• Update your master with the latest upstream version:

  git pull --ff upstream master

Git Commit Guidelines

We have a few guidelines about how our git commit messages should be formatted. This leads to more readable messages that are easy to follow when looking through the project history.

Commit Message Format

• Use the present tense ("Add feature" not "Added feature")
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit the first line to 72 characters or less
• Reference issues and pull requests liberally
• When only changing documentation, include [ci skip] in the commit description

Additional Notes