Basic Workflow in Github for Updating Existing Documentation

Owned by (OLD ACCOUNT) Erin Nettifee
Last updated: Aug 09, 2023
7 min read

Assumptions

The steps on this page assume the following:

  1. You have a github user account already created;
  2. You are using the Github web interface, not a desktop client or command line tool. (You can manage docs work with any Github tool, but the web interface is the easiest way to get started.)
  3. For each release, you have a fresh "forked" copy of the Docs repository that has the deployment branch for the release.

Step 1: In your forked repository, create a new branch for the changes that you are making to a single page or app.

Unless you are certain that you only have to make updates for one change in a release, it is usually easier to create a branch for updates to an app, and then make updates until you have all of the changes added for the release, and then send the PR over. 

Example: suppose that you are updating the documentation for the Requests app for the Umbrella release. You do a review of the jiras and find three new features, and one user interface change, that all require documentation updates. Rather than making four PRs for each individual change, create one branch (perhaps called "Umbrella-Requests") and make all the updates to the Requests.md file in that one branch, and then push the changes when you are done. 

Remember that branches can remain in your local repository and you can do as much work on them in ongoing fashion as you need to - that won't change anything on the main docs site until you create the PR and it is merged.

Example: Updating documentation for the Circulation Log in the Nolana release

Suppose that you have identified documentation changes that need to happen in the circulation log in the Nolana release.

  1. Go to your forked copy of the docs repository. In the branch list, you'll see that it defaults to "Main"
  2. Click the branch drop down and scroll to the Nolana branch. Click on Nolana to switch to that branch.
  3. Click the branch drop-down again. In the box, type "nolana-requests". Since you've typed the name of a branch that doesn't exist in your repository, Github gives you the option to "Create branch nolana-requests from Nolana". Click that option.
  4. Github creates the branch - you'll get a confirmation message, and you'll also see the new branch name in the branch menu.

Step 2: Using the Github web interface, make the updates to the content on the branch you created, in your copy of the documentation repository.

Content written in English lives in the Content/en/docs folder. The list of folder names should look familiar to you as the list of top options on the docs.folio.org sidebar.

To edit a page in this folder:

  1. Navigate to the page you want to edit.
  2. Click the pencil icon in the top right corner.
  3. Make changes to the page content.

To save your edits:

  1. At the top of the edit page, click the green Commit Changes button
  2. In the pop-up window, give your update a short title that conveys what you did, and additional context in the box if you think people would find it helpful. You can choose to either commit the change to your branch directly, or create a PR for your repository and then approve the PR. Unless you are working on something complex where you think you might need to roll back changes in your own repository, it is fine to simply commit the change directly.


Step 3: When you are finished, create a PR (pull request) to send your changes to the main FOLIO docs repository.

Once you have made all of your changes, you need to send your updates to the main FOLIO docs repository so they can be integrated into the production documentation. This is done by creating a "PR", or "pull request", between your repository copy of the docs site, and the folio-org copy of the docs site. 

There are various ways to create PRs, but I will just document one way to do so.

  1. Go to the folio-docs repository (https://github.com/folio-org/docs) and click Pull Requests at the top.
  2. On the Pull requests page, click New pull request
  3. On the New Pull Request page, click the option to compare across forks.
  4. From the Head repository menu, choose your account from the list
  5. From the base ref drop down, choose the branch on the production site you are merging documentation to.


  6. From the head ref dropdown, choose the branch you have been working on. 

Once you have the right base ref and the right base branch you were working on, you should get a screen like what is below.

  • You'll see the number of commits you made to your branch. If you had been working on something over time, you might see multiple commits. If you just had one change to make and then you were ready to make the PR, you'll just see the one change.
  • If you scroll down, you'll see the changed file with what was added or removed - that is another way to verify that you are on the right branch.

To create the pull request, click the green button for Create pull request.

On this screen:

  • If you are working from a documentation jira, put the number at the head of the subject line - that allows the documentation PR to be linked to the jira.
  • In the "Write" box, give a brief summary of what you updated. This shows up in github and is helpful for tracing work.

When you are ready to send the pull request, click "Create pull request".

Step 4: Sign the CLA license agreement (You only have to do this once)

The first time you submit a PR to the docs repository, you will get an automated reply from Github prompting you to sign the Contributor License Agreement. Click the link in the automated email from Github to sign the agreement (you will just authenticate with your github credentials to sign it - it's not actually a physical signature.)

Handling documentation updates for multiple flower releases

GitHub tracks the different versions of each piece of content. Docs.folio.org is configured to enable a drop-down list of releases (Honeysuckle, Iris, Juniper, Kiwi, Lotus, Morning Glory, Nolana, etc.). Each of those releases has their own branch in the documentation repository.

A change that has been merged to the main branch may also be needed for older flower releases, especially if you are fixing an error.

In order to change documentation for multiple releases, you need to create a pull request for each branch that you need to update, following the general directions on this page.

The general practice is to only go back and update older documentation for versions of FOLIO that are still supported. That includes the current and previous release. For example, suppose that you realize that when working on the documentation for Poppy, you realize there is an error in the documentation that has been present since the Lotus release. In that case, you would make sure the documentation is correct for Poppy, and then create a fix for Orchid (the current release) and for Nolana (the previous current release.) 

Using Git and "cherry pick"

If you are comfortable with using a Git desktop client, you can also do this with the cherry pick feature. This feature is not available in the Github web interface.

Command line example:
git checkout nolana
git checkout -b update-demo-site-links-nolana
Go to the pull request for the first branch, open the commits tab, and click on "Copy the full SHA" icon: https://github.com/folio-org/docs/pull/198/commits
git cherry-pick -x 92ba2799fb9e9a8e9c38ac2ae84a56f59ef4a0b9
The SHA can be pasted from the clipboard. If needed cherry-pick can process multiple commits/SHAs in one go. The -x will include the SHA(s) into the commit message, this speeds up the review of the following pull request because reviewers can click on the link to the original commit and can assume that the changes are the same. 
Push the branch and create a pull request against the older flower release branch.