Skip to content

Quire Technical Style Guide

Erin Cecele Dunigan edited this page Feb 2, 2021 · 2 revisions

PLEASE NOTE: This style guide is currently in process. Below are some basic development guidelines, but we will be adding here information to help contributors to structure and style their code to best integrate into Quire’s code base.

General Practices

To start, first clone the repository. From GitHub Desktop, select “File > Clone Repository ...” choose the corresponding gettypubs/quire repository you want to work on and choose a place on your computer to clone into.

Once cloned, start by making a new branch to work on. It should be lowercase with no spaces, and be descriptive of the work you’ll be doing: guide-edits, new-author-info, proofreading-pass, etc.

For the main quire repository, new branches can generally be made off of master.

With the new branch created you can work making improvements to the text or adding new material. Committing incrementally as you go. Commits should be centered around like items, such as changing the name of a single shortcode across multiple files, or implementing or re-working a single feature.

Once complete, select “Branch > Create Pull Request”. You will be taken to GitHub, where you can describe the overall changes made in the branch, and push the “Create Pull Request” button to confirm.

Once a pull request is made, the maintainer(s) will review it (currently @geealbers), and make any comments. If corrections or further work is required or suggested, you can make and commit them on the same branch you were working on. They will automatically be incorporated into the pull request.

Once the pull request is approved, the maintainer(s) will merge it, and the branch should then be deleted both at the origin (GitHub) and locally (your computer).

Special Notes for Quire Starter and Starter Theme

quire-starter-theme is included as a submodule of quire-starter. To work on either you need open your Terminal, move to the location where you’d like to put the file, and enter this command:

git clone --recursive https://github.com/gettypubs/quire-starter.git

This will clone quire-starter and, inside it, quire-starter-theme but each will still be connected to their own git repository. When you make changes to quire-starter-theme you commit them into that repository, but at the same time quire-starter is aware of these changes, and automatically shows a change to its subproject commit reference.

Subproject commit 09b1834149a09323aac2b00926181b72fbe9cb7f

This essentially says, that quire-starter should use quire-starter-theme at that particular point in its commit history. When you make a change in quire-starter-theme, that point has to move and so the commit number has to be updated. To keep the commit history clean, the new subproject commit number does not need to be committed into quire-starter with every change in the theme, but rather only a major intervals, or even only right before submitting a pull request.

When using GitHub Desktop, you would got to “File > Add Local Repository ...” twice. First to add quire-starter and second to add quire-starter/themes/quire-starter-theme. And you would toggle back and forth between them to make commits.

Issue Tracking

Rather than manage issues across all four Quire repositories, we post all issues on the main quire repository and tag them with their repository name(s) accordingly.

Clone this wiki locally