Submitting a Pull Request

Owned by Christine Di Bella
Last updated: Jul 20, 2020
2 min read

Anyone is welcome to submit a pull request to improve ArchivesSpace. If you are submitting code that will add new functionality or change or extend existing functionality in a significant way, we encourage you to review the ArchivesSpace Process for Evaluating Potential Feature Contributions to the Core Code first.

Mark Cooper created this short guide to submitting an ArchivesSpace pull request. Information on forking repositories and creating pull requests in general is also available from Github. Pull requests are evaluated by members of the Core Committers group according to the criteria described at Pull Request Process.

Preparation

Developers new to ArchivesSpace are advised to review the Technical Documentation:
https://archivesspace.github.io/tech-docs/

Hudson Molonglo have an introductory video series for developers:
https://www.youtube.com/playlist?list=PLJFitFaE9AY_DDlhl3Kq_vFeX27F1yt6I

Making a pull request

Examples will use git on the command line that should be copy-pastable on OSX and Linux.

Begin by forking the ArchivesSpace repository into your personal Github account, then download it:

--

git clone git@github.com:USERNAME/archivesspace.git && cd archivesspace

# make sure we are on master branch (never edit in the master branch directly!)
git checkout master

# add the ArchivesSpace project git repository as "upstream"
git remote add upstream https://github.com/archivesspace/archivesspace.git

# fetch all branches
git fetch --all

# sync your master branch with the project master
git rebase upstream/master

# push the latest code to our fork
git push origin master

--

You can repeat the above steps at any time to sync your local and remote forks with the main project (do not repeat the git clone and add upstream steps).

Now to make edits. If you are resolving a bug or feature reported on JIRA then your branch name and commit message should reference the JIRA issue number (otherwise name appropriately):

--

# create a branch to do work in (referencing a JIRA issue number)
git checkout -b AR-1189_preferred_cit_field_update

# make your edits then add and commit changes
git add modified_file1 modified_file2 [etc.]
git commit

# commit message (referencing a JIRA issue number)
AR-1189 Preferred citation export field tag update

# push your branch to your fork at Github
git push origin AR-1189_preferred_cit_field_update

Finally, make a pull request at github.

For more information on smart commits (referencing JIRA) refer to: https://confluence.atlassian.com/bitbucket/processing-jira-software-issues-with-smart-commit-messages-298979931.html

Bringing a branch up to date

If you worked on AR-1189_preferred_cit_field_update a while ago then the main project may have been updated in the meantime. You’ll want to bring your branch in line with your local forks master branch (which you will have rebased off upstream/master per the instructions above) to ensure there are no conflicts between your local work and the current state of ArchivesSpace.

After syncing master:

--

git checkout AR-1189_preferred_cit_field_update
git rebase master

# if there are conflicts you will need to resolve them, follow the “git status” cues

# update your remote fork branch
git push --force origin AR-1189_preferred_cit_field_update

--

Now make a pull request if the branch is ready for submission.