Skip to content

Contributing guide for Artefactual staff

Jump to bottom Edit New page
Sara Allain edited this page Feb 27, 2019 · 62 revisions

The workflow for Artefactual staff is similar to that of any other user, with some additional permissions granted. Make sure you do these two things first:

  1. Talk to an Artefactual sysadmin to get read-write permission for the archivematica-docs and archivematica-storage-service-docs repo
  2. Ask someone to invite you to become a member of the Artefactual GitHub organization

Once you have done those two things, you are ready to start editing the documentation!

The Archivematica documentation lives in two repositories:

Table of contents

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 Archivematica Issues repository with as much detail about the issue as possible.

To create an issue:

  1. Go to the Archivematica Issues repository.
  2. Click New issue and select the Documentation report template.
  3. 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.
  4. Fill out the body of the issue as per the issue template.
  5. Label your issue with the Type: Documentation label.

An example of a good issue from the Archivematica Issues repository is issue #267.

Set up your edit environment

Artefactual staff generally edit the documentation locally using a text editor so that we can use Sphinx's HTML document generator to inspect the results and look for errors. This is ideal for big changes to the docs, but has more overhead to set up. See editing locally for more information.

Alternately, you can make your changes from within the GitHub user interface. This is more user-friendly and easier to set up, and is perfect for small changes. See editing on GitHub for more information.

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.

You can make minor changes through the GitHub UI or by editing locally. To make a minor change through the GitHub UI, follow the steps in Contributing guide for community members > Create a pull request.

If you would like to make the change by editing your local copy of the documentation, follow the steps below:

  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

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. Please make sure to create an issue that you can link to before you start making major changes.

If you are making a major change, we strongly recommend editing a local copy of the documentation so that you can take advantage of Sphinx's HTML generation and error reporting. This reduces the risk that breaking errors will make it into the documentation. However, if you prefer to use the GitHub UI, you can follow the steps in Contributing guide for community members > Create a pull request.

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

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

  2. Create your local branch:

  • From the main branch that you are making edits to (i.e. 1.8), run git pull --rebase to ensure that you have the most recent version of the documentation.
  • Create a new local branch with git checkout -b dev/my-changes, replacing my-changes with a descriptive name that identifies the work that you are doing.
    • dev/ indicates that this is a development branch - that is, a temporary branch where work is being done. The branch name should reflect an identified problem. Ideally, 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/my-changes, replacing with the name of the branch that you want to fold your changes into (i.e. origin/1.8).
  • 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 on your computer.
  • Make sure to run make clean html regularly 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 pick up 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: enter your commit message, then ctrl+o, enter, ctrl+x
      • In vi/vim: hit i to enter insert mode, enter your commit message, then esc, :wq
  1. Push your changes:
  • git push -u origin dev/my-changes will send your branch to GitHub
  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.8). The compare branch should be the branch that you just pushed (i.e. dev/my-changes).
  • Add yourself as assignee, select reviewers, and add labels or milestones as required.
  • Click on Create pull request.
  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 pull request.
  1. Merge your pull request:
  • Once the pull request is approved and ready to go, click on Merge pull request.
  • The PR should now have the status of merged in the UI.
  1. Clean up:
  • Make sure that your work has been merged properly before you delete anything!
  • Delete the remote branch by clicking on Delete branch from the pull request screen.
  • Delete the branch on your computer with git branch -D dev/my-changes
  • 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/my-changes
  4. Rebase your local branch to pull in new changes: git rebase 1.7. You might have conflicts at this point! How you deal with them will depend on your setup. If you are using Atom.io as your text editor, opening the affected pages will give you a graphical interface to resolve conflicts.
  5. Once the conflicts are all resolves, 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~5, where 5 is the number of previous commits you want to see (you can change this if you want to see more or less). You will see a list like this:

    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 5 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 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 protected]>
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.

Check for errors with Sphinx

Sphinx is a documentation generation tool. It builds documentation much like how modern software is built and so it has the ability to spot issues with the way pages have been written, for example, detecting orphaned references to other pages.

Sphinx is executed using a local MakeFile at the root directory of archivematica-docs. The MakeFile contains a set of directives that can be used by the Make Build Automation Tool.

To see the full capabilities of the MakeFile you can run the following command from the terminal:

   $ make help

And the output will look something like:

   archivematica@artefactual:~/git/artefactual/archivematica-docs:$ make help

   Please use `make <target>' where <target> is one of
     html       to make standalone HTML files
     dirhtml    to make HTML files named index.html in directories
     singlehtml to make a single large HTML file
     pickle     to make pickle files
     json       to make JSON files
     ...
     ...
     ...

Running $ make html will compile the documentation and output a log:

   archivematica@artefactual:~/git/artefactual/archivematica-docs:$ make clean html

   rm -rf _build/*
   sphinx-build -b html -d _build/doctrees  -n . _build/html
   Running Sphinx v1.6.7
   making output directory...
   loading translations [en]... done
   loading pickled environment... not yet created
   loading intersphinx inventory from https://www.archivematica.org/docs/latest/objects.inv...
   intersphinx inventory has moved: https://www.archivematica.org/docs/latest/objects.inv -> https://www.archivematica.org/en/docs/archivematica-1.6/objects.inv
   loading intersphinx inventory from https://www.archivematica.org/docs/fpr/objects.inv...
   intersphinx inventory has moved: https://www.archivematica.org/docs/fpr/objects.inv -> https://www.archivematica.org/en/docs/fpr/objects.inv
   loading intersphinx inventory from https://www.archivematica.org/docs/storage-service-0.10/objects.inv...
   intersphinx inventory has moved: https://www.archivematica.org/docs/storage-service-0.10/objects.inv -> https://www.archivematica.org/en/docs/storage-service-0.10/objects.inv
   loading intersphinx inventory from https://www.accesstomemory.org/docs/latest/objects.inv...
   intersphinx inventory has moved: https://www.accesstomemory.org/docs/latest/objects.inv -> https://www.accesstomemory.org/en/docs/2.4/objects.inv
   building [mo]: targets for 0 po files that are out of date
   building [html]: targets for 46 source files that are out of date
   updating environment: 46 added, 0 changed, 0 removed
   reading sources... [100%] user-manual/translations/translations                                                                                                          
   looking for now-outdated files... none found
   pickling environment... done
   checking consistency... done
   preparing documents... done
   writing output... [100%] user-manual/translations/translations                                                                                                           
   generating indices... genindex
   writing additional pages... search
   copying images... [100%] user-manual/access/images/metadata_only_atom_2.png                                                                                              
   copying static files... done
   copying extra files... done
   dumping search index in English (code: en) ... done
   dumping object inventory... done
   build succeeded.

   Build finished. The HTML pages are in _build/html.

If there are any errors, they will be reported in the log. The default state is no errors. All errors must be addressed before the PR can be merged.

The output will be accessible from the _build/html folder. You can use these HTML files to view your changes in a web browser.

Two commands of significance to the user are:

  • $ make clean html will clear the _build/html folder which guarantees your documentation changes show up immediately on browser refresh. This can be useful if you do not see your changes after editing a page.
  • $ make dummy will perform all the Sphinx checks without building and outputting the HTML. This can be useful for testing your work as you go before outputting the HTML to look at in more detail.

Review a pull request

  1. In GitHub, find the PR you've been assigned 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, any member of the Artefactual organization in GitHub can merge the PR. GitHub should flag any merge conflicts. Make sure to thank the user for their contribution!

This wiki is maintained by staff at Artefactual Systems, the primary developers for Archivematica. Questions? Email us at [email protected].

Home

Clone this wiki locally