Skip to content

Contributing guide for Artefactual staff

Jump to bottom Edit New page
Sara Allain edited this page Sep 25, 2018 · 62 revisions

The workflow for Artefactual staff is similar to that of any other user, with some additional permissions granted. You will need to talk to an Artefactual sysadmin to get read-write permission for the archivematica-docs repo and the gitolite server. Once you have done that, you are ready to start editing the documentation!

Resources

Before contributing to the documentation, please read the following pages:

You may also find these pages helpful:

Create an issue

If you notice a problem in the documentation, start by filing an issue in the code repository with as much detail about the issue as possible.

Give your issue a descriptive title. If your issue describes an error in the documentation, start the title with the word "Problem", followed by a semicolon and a space. For example, issue 66 is titled "Problem: docs do not indicate new silent AIP compression behaviour", indicating that there is an issue in the documentation that needs to be solved. This convention is subjective; general suggestions for improvements to the documentations can omit the "Problem" prefix.

The body of the issue should mention, at a minimum:

  • The page (and section, if possible) where the problem occurs.
  • The version of the documentation you are consulting.
  • A proposed solution.

A good example from the archivematica-docs repository is issue #57.

To create an issue:

  1. Go to the Archivematica Issues repository.
  2. Click New issue.

Set up a local edit environment

Artefactual staff generally edit the documentation locally using a text editor on your computer, due to the configuration of our repositories - we use an intermediary server called gitolite to back up all Artefactual and Archivematica repositories, so branch management is a little more complicated than a regular GitHub process.

This is also recommended so that you can use Sphinx's HTML document generator to inspect the results and look for errors.

You must first install Sphinx and clone the documentation repository:

  1. Install pip: sudo apt-get install python-pip

  2. Install Sphinx: sudo pip install -U Sphinx

  3. Locate the clone link by going to the main page of the repository, clicking on Clone or download, and copying the URL. Ensure that you are cloning with SSH, not HTTPS. In this case, the SSH URL is git@github.com:artefactual/archivematica-docs.git

    • You must amend this URL to point to gitolite rather than GitHub. Ask another analyst for more information.

  4. Clone the repository: git clone git@[gitolite-url]:archivematica-docs.git

  5. Run git pull --rebase to make sure you’re up to date.

Make a minor change

Minor changes fix things like typos, formatting, or clarity. Generally speaking, there's no need for someone else to review these changes, and it's not necessary to create an accompanying Github issue.

  1. First, ensure that you have followed the instructions to set up a local edit environment.
  2. To see all branches, use git branch -a. Check out the branch you want to work on with git checkout <branch>, i.e. git checkout 1.7
  3. Run git pull --rebase to ensure that you have the most recent version of the documentation code.
  4. Change the RST files as needed.
  5. git add -A will add all of the changed files, or you can choose a specific file by using git add /path/to/file.rst
  6. Add a short commit message (50 characters or fewer) with git commit -m “My message here.”
  7. Push the changes directly to the repository with git push

Changes should appear on the documentation website within a few hours.

Make a major change

Terminology

  • Local branch: the branch of the documentation that you create on your computer, where you make your changes.
  • Remote branch: a copy of your local branch that has been pushed to GitHub
  • Main branch: the version of the documentation that you are going to merge your changes into (in the documentation repository, these are named 1.6, 1.7, etc.)

Steps

Major changes are things like documenting a new feature, adding or reorganizing a page, or substantially changing existing content. The review process ensures that someone else verifies the documentation before it is published. It's good practice (though not strictly enforced) to create an issue that you can link to before you start making major changes.

  1. First, ensure that you have followed the instructions to set up a local edit environment.

  2. Create your local branch:

  • Run git pull --rebase to ensure that you have the most recent version of the documentation code.
  • Create a new local branch with git checkout -b dev/whatever, where dev/whatever is the name of the local branch.
    • Start your branch name with dev/ to indicate that this is a development branch - that is, a temporary branch where work is being done. The name should reflect an identified problem. If it relates to an issue, reflect the issue number by calling it something like dev/issue-43-fix-mcp-links.
  1. Set the upstream branch:
  • See all upstream branches with git ls-remote
  • Set upstream branch with git branch --set-upstream-to=origin/<branch> dev/whatever, replacing with the name of the branch that you want to fold your changes into (i.e. origin/master, origin/1.7).
  • Check that branch is tracking properly by doing git pull --rebase - you should get an “up to date” message.
  1. Make your changes:
  • Make the changes to your branch by editing the .rst files.
  • Make sure to run make clean html to ensure there are no formatting or crosslink errors.
  1. Create a commit:
  • git status -s shows which files have been changed.
  • git add -A will add all of the changed files, or you can choose a specific file by using git add path/to/file.rst
  • There are two ways to add a commit message:
    • For a short message (50 characters or fewer), use the -m flag followed by your message in parentheses - git commit -m "This is my commit message"
    • For a longer message, entering git commit will take you to an editor where you can add more information, including multi-line and formatted text. Save your changes and exit the editor.
      • In GNU nano: ctrl+o, enter, ctrl+x
      • In vi/vim: esc, :wq
  1. Push your changes:
  • git push -u origin dev/whatever will send your changes to Github, where they can be reviewed.
  1. Create a pull request:
  • Go to the project in Github and click on Pull requests, then New pull request
  • The base branch should be the version of the docs that you want to merge your changes into (i.e. 1.7). The compare branch should be the branch that you just pushed (i.e. dev/whatever).
  • Add yourself as assignee, select reviewers, and add any labels or milestones that you need.
  • Complete PR
  1. Wait for someone to review your pull request.
  • Based on their feedback, you might need to make more changes. Simply make your changes, then repeat steps 4 and 5 above. The new commits will be added to the PR.
  1. Merge your pull request:
  • Do not use the merge button in the interface! Currently, this has to be done from the command line.
  • Check out the branch that you are merging the commits into (i.e. 1.7)
  • Merge the commits using git merge --ff-only dev/whatever. --ff-only ensures that the commits are merged one after another, not on top of each other.
  • git log shows the commit log so that you can be sure that you're merged the right stuff .
  • git push pushes the changes to the remote branch.
  • The PR should now have the status of merged in the UI (it’s purple!).
  1. Clean up:
  • Make sure that your work has been merged properly before you delete anything!
  • Delete the remote branch with git push origin --delete dev/whatever
  • Delete the branch on your computer with git branch -D dev/whatever
  • Close the issue, if there was one.

Changes should appear on the documentation website within a few hours.

Rebase your branch

Sometimes there's a gap between pushing your branch up to Github and merging it into the main repository. During this time someone else might merge their changes to the main branch - meaning that your local branch isn't up to date. Worry not! It's easy to rebase your branch to include their work.

The instructions below use 1.7 for the main branch; replace 1.7 with whatever branch you are merging your changes into.

  1. From the terminal, check out the main branch: git checkout 1.7
  2. Pull down the changes into the main branch: git pull --rebase
  3. Now check out your local branch again: git checkout dev/issue-85-add-readme
  4. Rebase your local branch to pull : git rebase 1.7
  5. Push your changes to the remote branch: git push -f

Squash your commits

If your pull request includes many small commits, it's good practice to squash them into one big commit for the hygiene of the repository. To squash your commits, follow these steps after pushing all your changes to the remote branch but before merging your changes into the main branch.

This is optional. Proceed with caution!

  1. Check out your local branch

  2. Run git rebase -i HEAD~8. This will display a list like this:

    pick 6b3cd38 Issue 954 update ubuntu firewall instructions
pick 636c4b3 Issue 954 incorporating edits to Ubuntu install instructions
pick 23c5ac7 Add outline of AtoM DIP Upload process
pick 42d49a1 Remove 'Interface options' from docs in Admin tab, #98
pick 331d2a3 Minor update to CentOS install instructions
pick b40014f first pass at a README for the docs
pick cac51ff Fixed some typos!
pick 11ed62d Fixed typos and abbreviations

    This is a list of the last 8 commits for the repository. Note that it's in reverse order - the bottom commit is the most recent one. Instead of merging three commits, two of which are minor fixes, it would be tidier to have one commit that included those fixes. To squash them together, you'll need to decide which changes are minor (or fixups) - in this case, both the typo changes.

  3. Hit i to enter edit mode. Change the word "pick" to "fixup" for both of the minor changes, so that the list looks like this:

    pick 6b3cd38 Issue 954 update ubuntu firewall instructions
pick 636c4b3 Issue 954 incorporating edits to Ubuntu install instructions
pick 23c5ac7 Add outline of AtoM DIP Upload process
pick 42d49a1 Remove 'Interface options' from docs in Admin tab, #98
pick 331d2a3 Minor update to CentOS install instructions
pick b40014f first pass at a README for the docs
fixup cac51ff Fixed some typos!
fixup 11ed62d Fixed typos and abbreviations

    This will merge the two fixups into the commit above them.

  4. Save your changes and exit the editor.

  • In GNU nano: ctrl+o, enter, ctrl+x
  • In vi/vim: esc, :wq

  1. Now run git log -1. This shows your latest commit. It should be the main commit.

    commit 0ce8add48e339acdd5e1c3e2762347d1562b195f
Author: username <email@example.com>
Date:   Wed Mar 14 15:54:08 2018 -0700

    First pass at a README for the docs

  2. Force push the fixed-up commit to the remote branch with git push -f

  3. Now merge your local branch into the main branch as usual, following step 9 in the major changes section above.

Review a pull request

  1. In GitHub, find the PR you'd like to review.
  2. Click on Files changed and then Review changes to comment on the documentation and/or approve the changes.
  3. The original author can then merge the PR.

Merge a community PR

After reviewing a non-Artefactual user's pull request, it can be merged by following the steps below.

  1. Go to the user's Github page and get the URL of their branch.

  2. In your terminal, add the user's branch: git remote add -f name https://github.com/user/whatever.git

  • Note that name can be anything you want.
  1. Cherry-pick the commit: git cherry-pick 5ba3d7b
  • The numbers and letters at the end represent the unique alphanumeric hash of the commit. The first seven numbers are usually unique enough, but you can also grab the full hash by copying it from *Commit tab of the PR.
  • Note: if there are multiple commits, cherry-pick each commit into the branch, starting with the earliest. Then squash the commits following the Squash your commits instructions above.
  1. Push to the remote branch: git push

This wiki is maintained by staff at Artefactual Systems, the primary developers for Archivematica. Questions? Email us at info@artefactual.com.

Home

Clone this wiki locally