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 v4 user documentation, a manual for installation and configuration of the app for the non-developer crowd.

If, during any of the your work with Arches, you have any questions about how to use Arches, please direct them to the Arches Forum. The forum allows us to share feedback and answers with the great Arches community.

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 a few ways to contribute:

• Logging Issues and Bugs
• Contributing Code
  • Commit Message Guidelines
• Contributing Documentation

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. Please take a minute to search through the open issues in the repo, and if you find one that matches your own, feel free to comment and your thoughts.

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.

Contributing Code

We strongly encourage code contributions. To begin, you should begin by forking the Arches repo. Then, follow our Developer Installation guide, and clone your own fork, not the official archesproject repo. Once you have Arches fully installed using your own fork of the repo, you are ready to begin.

Submitting Code

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 (lower) case.

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

• In your forked repo, create a branch, using the naming template shown above:

  git checkout -b 1231_cool_new_feature master

• Make changes to the code-base, only those that will address the new feature/bugfix that you named the branch after.

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

  git commit -a

  Note 1: The optional -a flag will automatically "add" and "rm" all files that you have edited.

  Note 2: If you have created or deleted files in the file system, you'll have to precede this commit command with git add . which with add these new (or deleted) files to your git index.

• Test your changes locally to ensure all the tests pass (make sure your virtual environment is activate first):

  python manage.py test tests --pattern="*.py" --settings="tests.test_settings"

• Push your branch to GitHub:

  git push origin my-fix-branch

• This will create an new branch on your remote forked Arches repo.

• To send a pull request to the official Arches repo:

  1. In the Arches repo, go to "Pull Requests" and choose "Create New Pull Request".
  2. Click the link to "compare across forks".
  3. Set your repo as the "head fork", and select the branch that you want to merge.
  4. Create the pull request, complete with descriptions of changes. If applicable, connect the PR with the issue it addresses. GitHub Documentation on creating a pull request from a fork

• We may suggest changes to the code before the pull request is approved. If that is the case:

  • Make the required updates.
  • Re-run the test suite to ensure tests are still passing.
  • Commit your changes to your branch.
  • Push the changes to your GitHub repository (this will update your Pull Request).
  • You do not need to make a new 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
• Make sure every commit references an issue, for example "improve contributing guidelines docs #1926"
• When only changing documentation, include [ci skip] in the commit description

Contributing Documentation

If you are so inclined, we greatly appreciate any help in adding to the Arches documentation. This could include creating example videos/workflows, to-do tasks, etc. As you may be aware, our documentation can be found in a few places:

• This Wiki.
  • This is where we document the more technical side of Arches, from command line operations to the actual data model. We also have some step-by-step instructions for development/production strategies. We always love your feedback on what's here, or any contributions you would like to add.
  • To contribute to the wiki, use the same fork method as described above, but note that the wiki is actually a separate repo. This stack exchange q/a should help you get started.
• The official Arches v4 Documentation on readthedocs.
  • This documentation is for Arches users (as opposed to developers) and is more focused on the app's UI.
  • To contribute to this documentation, fork the Arches repo as described above.
  • The contents are stored in arches/docs/. The files are automatically built by readthedocs from the master branch. The .txt files are reStructured text, and built with Sphinx using the readthedocs theme. You can preview your changes locally by running make html in the docs directory, and opening _build/html/index.html in a browser.
• The Arches "in-app" help menus.
  • This documentation is accessible from within the Arches interface, and is meant for quick reference.
  • To contribute to this documentation, fork the Arches repo as described above.
  • This content is stored as HTML templates in /arches/arches/app/templates/help and they are loaded on a "per view" basis, as you can see in this example from the graph settings view.