iTC Advanced User Guide for GitHub Offline

Audience

This is designed for a user who will be doing more heavy editing of documents within the iTC.

This document intends to communicate to iTC users information regarding the selection of clients to interact with GitHub and some of the workflow considerations when working offline (as opposed to online via web browser). This guide builds on the information in the iTC User Guide for GitHub.

The expectation for any user reading this guide is that they are already familiar with GitHub or have at least read the iTC User Guidance for GitHub and understand the process for creating Pull Requests within the web interface.

Resources

1. Using GitHub with a Client

Generally, GitHub clients focus on the process of creating Pull Requests within GitHub. Things like Issues are handled in the web interface (though you can still reference them in your comments about a Pull Request), but the primary (and in some cases only) purpose of the client is to manage the process of downloading the latest updates and uploading your edits.

It is important to understand that a GitHub client is not an editor. Some clients may be able to link to an editor (so you can click on a file while inside the client and have it open up), but the client itself is specifically for managing the upload/download of code (in this case the iTC documentation).

What the GitHub client will do is to allow you to download the files of the repository where you are working (such as the cPP repository), and then work on the files from your local computer (as opposed to using the browser). For this you can use any editor you like (see Asciidoctor Editors for some suggestions). Once you have completed your edits and saved them, you can then upload them back to GitHub where they can be reviewed and eventually included in the final version.

2. GitHub Clients

When working offline, you will need to have some sort of GitHub client to interact with the repository. There are many options, and a lot of them are free (some are more free than others), covering both GUI and CLI-based clients. The page GitHub Clients Overview provides links to several different clients that can be used for managing your access with GitHub. None is really better than another, it all comes down to preference.

Once you are familiar with how GitHub works, with Pull Requests and Merges, using any client is more about figuring out how that client presents those functions than it is how to do what GitHub needs.

For the purposes of this document, the GitHub Desktop client will be used.

3. GitHub Desktop Client

3.1. Setup

The configuration of the GitHub Desktop client can be found here. This page describes all the steps necessary to install the client and to authenticate to your GitHub account.

3.2. Adding (Cloning) Repositories to the Client

Within each GitHub organization you will have repositories where you do the work. While a repository in the web interface shows Issues, Pull Requests, the wiki and other options, in the client you are looking at the Code and Pull Requests sections only (it is possible some clients may provide more functionality, but not in the client we are looking at now).

Accessing a repository will make it available to download to your computer. When you installed the client it would have asked you to specify a GitHub folder, and this will be where the files are downloaded (by default).

The process of adding a repository is called cloning. The directions for cloning a repository can be found here. When you select GitHub.com you will see all the repositories you have access to (such as different iTCs, or different repositories within your iTC). Select the repository you want to access and where you want the files to download to (this will be your working directory).

3.3. Working With Local Repositories

3.3.1. Working in Branches

The first thing to remember when working offline is to consider the branch you are working in. There are 2 branches by default in the repository, Master and Working. When you are working offline or even online, generally you want to commit your changes to a new branch with a Pull Request. The Pull Request lets everyone in the iTC see the specific changes you have made to the existing document (or just see that it is new), and then to approve its inclusion into one of the main (usually Working) branches.

While it may be possible to commit directly to the Working branch, this is not what you want to do as this can circumvent the process of approvals and can cause conflicts with other people working on the same document (in the same place). The purpose of using GitHub is to allow multiple editors at the same time, and the branch process is how this is managed.

When you are going to begin work on your documents offline, the first step is to create your own branch to work in. This will let you work on your changes without impacting any other work until you are ready to upload them into a Pull Request.

Any branch is based on an existing one. Generally this would be Working (i.e. when you create your new branch, it will use Working as the base for the changes), so your changes will be compared to what is the current status of the Working branch.

It is possible to work on multiple separate branches at one time though this isn’t recommended. The way the client works, you always look at a single branch at a time. So if you move between branches, changes from one will not be reflected in another.

For example, if you create a new file <file1.adoc> in branch 1 (based on working), and then start a new branch 2 (also based on Working), <file1.adoc> will not appear in branch 2 because both branches are based on the same original branch.

It is possible to create new branches from something other than Working, and that can be useful (such as making an edit to another Pull Request), but generally you will perform all the work in a single branch at a time.

To create your new branch, follow the steps here.

3.3.2. Switching Between Branches

While you are working on your branch changes, you may need to see work being done in another branch (i.e. a Pull Request) that has already been uploaded. The steps for switching can be found here.

One of the main things to note when switching between branches is what happens to your changes. When you switch branches, you will be asked what you want to do with any changes you have already made. They can be brought to the new branch or to leave them in the existing branch. You should leave your changes in the existing branch, and GitHub Desktop will handle saving them and then showing you the new branch. When you switch back to your previous branch, the changes will be restored, or you will have the option to restore your stashed changes. This allows you to move around in the branches without losing your work.

The option to bring your changes to the new branch is very helpful in cases where you forget to start a new branch before you start editing. If you start working on a document and then remember to make a new branch, you can bring all the changes forward into the new branch this way.

3.3.2.1. Working in a Pull Request Branch

Once someone has uploaded a new branch and created a Pull Request it is generally best to make edits for that branch from that branch. For example if branch3 was created to edit a file and a Pull Request was created for it, for you to make changes, you should switch to that branch and make the changes directly there. These will be shown in the Pull request separately and can be handled there, without needing to create additional branches.

3.3.3. Reviewing Branch Changes

When you are ready to upload your changes to GitHub, you will be saving a commit (this is the term GitHub uses, and is based on a hash value of the changes).

For more information about reviewing and committing changes to GitHub, go to here.

Opening the GitHub Desktop (which should be on the branch you had created already) will show you a list of the changed files on the left side. In the right pane the changes of each file will be displayed (so you can take a quick overview of any edits). Files will be marked with symbols for new, modified or deleted files (green, yellow and red, respectively).

If for some reason you don’t want to include the changes to one of the files in the Pull Request, you can uncheck it before making the commit. If you decide you don’t want the changes at all, you can Discard them (this can be right with a right-click). Note that a Discard will actually delete all the changes, so be careful about using this option.

To commit your changes to GitHub, fill out a title and description in the lower-left corner. If this is a new Pull Request this is the content of the initial comment for the discussion, while if it is an update to an existing Pull Request it will be shown as part of the commit within that discussion.

You can use the @ (to reference other iTC members) and # (to reference Issues or Pull Requests) references as you can in the web interface (more information can be found in section 3 of the iTC User Guidance for GitHub. Once you have completed this and selected the file changes to include, click the Commit button.

Once the commit has been created it needs to be pushed to GitHub. In the upper right hand corder (next to the branch menu) you will see "Push origin". Click this button to upload the changes to GitHub.

3.3.4. Keeping Branches Up to Date

One important taks is making sure that you local branches are up to date. Most of this is handled automatically, but sometimes it may need to be done manually.

When you have selected the branch you want to review, the button to the right of the branch menu will say Fetch origin. Clicking this button will tell the client to contact the server and make sure it has the latest copy of the specified branch. More information about this can be found here.

4. Local Editing with Asciidoctor

Once you have the files for the repository downloaded locally, you need to find (or have?) something to edit them with. Now given that Asciidoctor is simple text, technically something as simple as Notepad is sufficient, but the reality is that if you are taking the time to download the files and work offline, you probably want something with more functionality. Using Notepad will only let you see the text and syntax you have added, not give you a WYSIWYG (Live Preview) version.

The Asciidoctor Editors with Live Preview page has a lot of options for a Live Preview environment for Asciidoctor files. Realize that none of these are quite like using Word where you are directly editing the rich output, but are in some form a dual display with the raw Asciidoctor text in one frame and the rich output in another.

4.1. Recommended Editor (from Brian Wood)

At this point, the editor I would most recommend, is AsciiDocFX. While a little slow (it is cross platform Java, so it can take a little time to start up), I generally have not had any problems with it running and doing what it is supposed to. It is also the easiest to setup as it has everything you need bundled into it whereas several of the others require installing an editor and then loading plugins to support the preview.

AsciiDocFX provides a two-pane display with the raw Asciidoctor text on the left and a Live Preview on the right. You can open multiple files in tabs and there is a folder/file list on the left so you can find files to open (if you haven’t associated the files in Windows Explorer). There are also some help icons (things like bold text, headers, tables, etc.) that can be used to help out in formatting.

Generally the two panes are kept in sync (not always perfect at the bottom of the page, but pretty good), and you can use the preview side to navigate to places in the text (i.e. you can scroll through the live preview side and then click on the section where you want to edit something and the raw page will navigate to that spot immediately).

Atom and Brackets both seem to be pretty good editors, but I don’t find their preview to be quite as good, especially since the scrolling is not linked between the raw and preview panes. Note that Brackets does have a nice feature though where the preview window can be split out into a new window (as opposed to two panes in the same window), but I still find the lack of scroll sync to be a problem.

A few notes about AsciiDocFX to be aware of:

The output tools that are built in are fine, but do not have the full features of the Asciidoctor toolchain, so "final" documents should not be produced from here. This especially includes things like the special admonition notes that have been added, they will not be displayed properly here (or in any of the Live Previews)
Special admonitions will not be displayed properly (they will be shown in a box, but the marker for the icon will be ignored). They will still be shown in the final output if the Asciidoctor toolchain is used for building the docs
It is possible to paste binary characters into this editor but they will not show up in the display (it will be a blank space on the screen). I did this several times and it caused the file to be registered as binary in GitHhub instead of text. I had to use a standard text editor (like Notepad) to find and remove the characters

4.2. Ascii Diagrams

While there will be times when a complex graphic just needs to be created in a graphics program, for flow charts and requirement hierarchies, it is possible to use [ditaa] to create diagrams in text (Ascii art) and have them rendered into graphics in the final publication.

Ditaa is the recommended method for doing this, in large part because the setup is simple within Asciidoctor and also because it is simple to understand. Because you are using text to draw the diagram, it also means you can see exactly what you are doing within the text of the Asciidoctor document instead of needing to look up the graphic image. Using ditaa, when the HTML or PDF output is generated, the text is translated into a graphic image.

The biggest problem with any graphic is creating it, and Ascii diagrams can be particularly annoying since you are trying to line up the lines and text using spaces in within the document. To speed up this process, it is recommended to use [JavE] to help create the diagrams. Using JavE you can create diagrams in a more familiar way (like drawing boxes and lines with a mouse) and then copy the resulting output into your Asciidoctor document.

After reviewing the ditaa site about diagrams, you may need to create a user defined box style to get the right corners. The standard + will create square corners, while you will need to use / or \ for rounded corners.