Entering Changes with GitHub

Here are the main steps for entering changes in a Quire project:

1. Create a new branch in GitHub Desktop
2. Open Visual Studio Code and make changes to the Markdown & YAML
3. Commit your changes with GitHub Desktop
4. Create a pull request and request review

Changes will be entered in two phases. First pages and Second pages. See our Workflow to learn more about what occurs during each of those phases.

Create a New Branch

The first step in entering changes to a Quire project is to create a new branch (learn how to do that in the GitHub section of the Quire documentation.) A branch is a parallel version of your project that you can edit in directly without compromising the main version. When you go into your home directory and view your Quire files, what you see is based on whatever branch you currently have open in GitHub Desktop. If you change branches, the info in the files will change accordingly.

You will need to make new branches during the different phases of the Quire editing process. We use different branch naming conventions to reflect what phase of the editorial process the publication is in. When creating a new branch, do not branch off the main branch. The Quire team will make various branches for you to use as a base.

First-pages branch

The Quire team will create a first-pages branch to transfer the manuscript into Markdown and create the overall layout of the publication.

Second-pages branch

Once corrections to first pages are ready to be entered, the Quire team will create a second-pages branch. When entering corrections from the first round of edits, your branches should be made off this second-pages branch. The first-pages branch remains unchanged because it represents the publications at the time first pages was delivered to Editorial.

Final-pages branch

For corrections to the second pages round, the Quire team will create a final-pages branch. As before, your branches should be made off this final-pages branch when entering corrections from second pages.

Branch Naming Tips

Branch names should not only indicate what editing phase you are in but also who is doing the work and, when applicable, what work is being done:

• second-pages-[name] (i.e. second-pages-laura)
• second-pages-[name]-[task] (i.e. final-pages-laura-edit-captions)

Additional tips for naming branches:

• Keep branch names concise
• Words must be separated with dashes (GitHub won’t permit spaces)
• Do not use uppercase letters
• Every time you open the project to work on it, make sure you are working in the correct branch.
• If you do accidentally start making changes to the wrong branch, don’t worry. You can still create a new branch or switch to a preexisting one and take your uncommitted changes with you.

Working with Multiple Collaborators

When working with multiple collaborators, it is very important for each individual to work in their own branch. This allows you to review changes and identify possible conflicts before they are incorporated into your project. You can think of branches as safe spaces to experiment.

If multiple editors are inputting corrections simultaneously, it is best to work one at a time. Otherwise, you run the risk of creating conflicts should you both edit the same page (for example, if making changes to captions in the figures.yaml). Once a pull request has been approved and merged, the next editor should hit “Fetch Origin” to pull down the recent changes before creating their new branch and starting edits.

Open Visual Studio Code and Make Changes

The next step to entering changes is opening Visual Studio Code and making changes to the content of your publication. Your main focus will be on the content directory. As explained in Navigating Quire, changes will be made to the individual .md files as well as the .yaml files found in the _data folder.

Markdown & YAML Tips

Here are some things to look out for when working in Markdown and YAML.

• When italicizing a phrase make sure you do not italicize any surrounding punctuation.

  *I am italicizing a phrase*!

• When creating figure callout links, surround the text that you want to link in square brackets, and follow it immediately with parentheses surrounding a hashmark and the id of the image: [fig. 3](#fig-3). The image id is the same used in the figure shortcode.

• Watch horizontal spacing. YAML items should always line up and be uniformly indented. Improperly formatted YAML can temporarily break Quire functionality.

• Copy and paste your YAML blocks into a validator like the Code Beautify YAML validator to make sure there aren’t any hidden errors.

• YAML block entries can be in any order.

• YAML values must always be surrounded by straight quotes (" ") to ensure Quire reads the data correctly.

• Sometimes a caption for a figure will also require quotes leading to two sets of straight quotes which will create an error. To avoid the error you will need to use curly quotes instead. To achieve this, highlight the phrase in question and click Option-[(left square bracket) this will surround the highlighted text in double curly quotes. Another option is to copy and paste them from https://unicode-table.com/en/.

  "This is my caption with “Curly quotes” inside it."

• As long as you always use straight quotes on the outside of your YAML text you can add colons and markdown formatting for italics.

  "This is my caption with “Curly quotes” inside it: which also works for *markdown italics* and colons."

• This may also come up if you are using two apostrophes in a title. The apostrophe may appear as ’ in the preview, even when surrounded by quotes. You’ll need to replace the straight apostrophe with a curly apostrophe. To do that use Option + ] (right square bracket). Another option is to copy and paste them from https://unicode-table.com/en/.

Commit Your Changes

The great thing about working in GitHub is that you don’t need to worry about accidentally messing up the publication, even if you aren’t a technology wiz. GitHub saves the entire version history of your project (including deleted files) enabling you to track changes, revert changes, and restore earlier versions. To help the reversal process run smoothly, edits are saved in small groupings of meaningful changes known as “commits”. A commit is a record of a change or revision you have made to your Quire project. Commits can be a bit tricky to wrap your head around, so here is some advice for how to think about commits.

Commit Tips

• The summary should be a phrase that completes the sentence “This commit will __”.
• Use present/imperative tense, such as “Add contributor names and bios;” “Fix typos in section pages;” or “Change header color.”
• Keep the commit name concise (around 50 characters max). You can think of this as akin to an email subject line.
• Commits should be grouped consistently and logically.
• Commits should also be done in such a way that if an editorial decision gets reversed later, it is possible to reverse those specific changes without also reversing other important edits. For example, a global change, like altering the spelling of “catalog” to “catalogue,” should be committed separately and not lumped together with the rest of “Edit cat # 1.” Otherwise, if you decide to revert back to “catalog” later, it will reverse all other edits saved in “Edit cat # 1.”
• Make small commits and commit frequently.
• If you need to explain the commit in greater detail, use the description field (around 72 characters max). You can think of this as the email body. It is also ok to leave this section blank.
• Changes are organized by the .md file in which they were made. Keep this in mind if making multiple types of changes to one file. You may want to split the work up into different commits.
• Use the checkboxes at the left-hand side of your window to select which changes will or won’t be included in a given commit.

Here are some examples of good commits:

• All copyedits related to a single chapter, including changes to the captions, references, and object information
• Resizing all images in the publication to a standard size
• Making all changes necessary to fix a single bug
• Fixing an occurrence of a misspelled name throughout the book

If you accidentally made a commit and don’t want to save it you have a few options:

• If it’s something small, simply go back and fix it in the text.
• For the most recent commit you will see an “undo” button to the right of where it says “Commit to [branch-name]”.
• You can also view all the recent changes you made by clicking the “History” button just above the list of changes on the left-hand side. This will list the entire history of your commits. If you right-click a commit, it will give you the option to “Revert Changes in this Commit” (but be careful as you may end up reverting more than you realize.)

Create a Pull Request

After you commit your changes and push them to GitHub.com, you will see an open to create a pull request. A pull request is a request for either the digital team or another colleague to review and comment on your work. Pull requests must be reviewed by a colleague, either within editorial or on the Quire team before officially merging them into the project.

When creating a pull request make sure to take the following steps:

• Choose your reviewers
• Title the pull request. “Edit/[brief description]”
• Briefly explain what changes were made in the pull body of the pull request

You may be asked to make changes to your pull request before it can be approved and merged. If that’s the case, simply go back into your branch, make the required edits, commit those changes, and then push them to Github.com via the button at the top right of your GitHub desktop. They will automatically be updated in the pull request. Send a note to your reviewer via the dicussion section on the original pull request in GitHub so they know the changes have been made.