githubtraining / training-manual

Home of the words in the GitHub Training Manual and teaching scripts.

GitHub Training Manual

Welcome to the GitHub Training Manual repository. In this repository, you will find the content used by the GitHub Professional Services team during our official GitHub training courses and the scripts used when teaching.

The content is all written in Markdown, and the scripts are shell scripts.

Technologies used

This manual is served using GitHub Pages and docsify, and can be found at githubtraining.github.io/training-manual.

Goals and scope

The goal of this project is to serve as a content source for training on Git and GitHub. While GitHub, select GitHub Partners, and select customers may have their own use case directly with GitHub, the content is open source so we can share and improve as a community. You can find more information on contributing in the contributing guide.

The topic scope is limited to GitHub's core product features, on GitHub.com and also for GitHub Enterprise users.

Deploy the manual

These manuals are designed to be generated using docsify. To get your own manuals up and running, all you have to do is:

1. Fork this repository
2. In your fork, click on Settings
3. Scroll down to the GitHub Pages section, and set Source: to main branch /docs folder.
4. Click Save.
5. Return to the GitHub Pages section of Settings, and you'll receive the URL of your published manual.

Make changes

The official docsify documentation is your best bet for getting up to speed with the tool.

In general, you'll find all of the manual content in the docs/ folder of this repository. All content is written in Markdown, and it's all stitched together in docs/_sidebar.md, which specifies the order and hierarchy of the content.

Preview changes on your machine

You can install, and serve the contents of the docs/ folder locally with minimal setup. The steps are thoroughly described in the doscify quick start guide.

You can also simply run the following scripts:

script/bootstrap
script/server

Generate a PDF

Docsify doesn't currently support creating PDFs, but you can generate one using GitBook legacy. We've tried to make this simple for you by creating script/generate-pdf. The legacy version of GitBook is being shut down soon, but it still works. You'll need to follow the installation instructions below to install GitBook. The previous installation instructions on the GitBook site have been removed.

GitBook dependency

1. Download and install Calibre.

2. Run Calibre once to set up the application.

3. Make sure that the Calibre command line interface is available on your path. This is located at /Applications/calibre.app/Contents/MacOS/ on macOS if you are running the application from the default location.

Teaching scripts

Scripts that accompany the manual, and their documentation can be found in the script/ directory. This repository includes development container configuration. So you can run the scripts on the Visual Studio developer container or GitHub Codespaces.

License

Please see the license for detailed information. When using the GitHub logos, be sure to follow the GitHub Logos and Usage guidelines.

training-manual's Issues

Configuration parameter for GH page URL

While writing my previous issue, it spawned another idea. Do we want to add the GitHub pages base URL as another configuration parameter for the scripts and use that throughout? Makes way more sense than me editing every single reference I find as I work through the various scripts, and it might be useful for others trying to use this against their GHE instance.

Open sourcing this repository

Hello all! 👋 @githubtraining/trainers (and shoutout to @amyschoen and @Blackbms / @mblack88 !)

I would like to start a discussion around open sourcing this repository. I don't think we would get huge influxes of contributions or requests for changes. BUT, I do think the potential benefits are many - for translations, small improvements, and generally being good examples of open source.

This would require some steps before just flipping this to public, including looking for any sensitive information we'd want to remove. Before we get to that point, @githubtraining/trainers @amyschoen @mblack88 (and also @matthewmccullough as I recall you being in favor of open sourcing this), do you have any strong opinions, questions, or general comments on this topic?

Add note about authentication in manual

We should consider adding authentication troubleshooting:

---

Authentication Troubleshooting Guide

The following are reasons you may be having trouble performing network operations, these include: clone, push, pull, and fetch. Try diagnosing each problem and solution in the order we've presented them.

1. Have you told Git to remember your credentials in the past?

Yes - You may have cached outdated credentials. Ask Git to forget them with git config --global --unset credential.helper. You may have to try --system instead of --global.

No / I don't know / I don't remember - You should be seeing a prompt to enter your GitHub username and password each time you perform a network operation. If you don't, you've probably cached your credentials without realizing it.

2. Are you cloning with HTTPS?

Yes

• It's possible you've got 2FA set up. In order to be able to clone from the command line with HTTPS, you need to use an access token..
• If that still doesn't work, you can attempt to clone with SSH.

No / I don't know - Try cloning with HTTPS, which is the recommended method for cloning.

3. Are you behind a firewall?

Yes

• The company firewall may be blocking access to GitHub, ask your employer or network adminstrator if you can use a proxy to get around the firewall..
• If the server you are cloning your repository from is anything other than GitHub.com, there might be something wrong with the SSL certificate. You could allow Git to accept a self-signed certificate with git config --global http.verify false

No - It's possible that you've previously configured a proxy to bypass a firewall. You can unset such a proxy with the command git config --global --unset http.proxy. You may need to use --system instead of --global.

I don't know - Ask your employer or network administrator if you're behind a firewall.

GitHub Training Guide - possible issues in the English guide reported by translators

Hi @brianamarie

The translators working on the Japanese translation of the GitHub Training Manual reached out to me to report the following:

• The text "allows you to see" is repeated twice

- They also mentioned that in the files app_Day_1_activities.md and app_day2_mergeconflict.md that the list items all say "1" and they were wondering if this was an error.

I'll let you know if I get more feedback.

Thanks

Alexandra

Sharing new content with external trainers

@deepakarchinnova brought up the slack notifications about progress in the GitHub for Managers #64 PR, and asked about how he could be enabled to deliver this content as well.

How can we enable other trainers on new content, whether it's a new course, or updated content? cc @githubtraining/trainers

• Recorded brown bag sessions over the content?
• Opportunities for 1:1s?
• How will we practice teach-backs?

Extra files are created for users that comment more than once in the day 1 repo

To demonstrate this issue, I created a new caption-this class repository named parkerbxyz-duplicate-example using option 1 in the teach-class script. Then I went to the first issue and added three comments. When I ran teach-script again and selected option 2 to add collaborators and create files, the script created three different files for me and listed my username three times in this issue.

I spent some time trying to add deduplication logic to the create-files script, but I wasn't able to get it working. I'm hoping somebody with more Bash experience than myself might be able to help.

Check the PDF documentation for Windows

GitBook is making some changes.

Short term

• @amyschoen has made updates to the documentation to work around this (#195)
• We still need to make sure these instructions will work with Windows (@mblack88 if your team is still using PDFs, would you be interested in testing this?)

Long term

• We'd like to explore a more native Docsify solution #193

Clone repos from the proper source

training-manual/script/create-repo

Line 37 in 4fb1d23

git clone --bare https://github.com/githubtraining/$type $reponame >> log.out 2>&1

I noticed when things weren't working out as expected that it was going out to GitHub.com to clone the template repos there instead of the local copies of the template repos that I migrated over. In my mind, we'd always want to clone down the local copies if we're in GHE mode for subtle reasons like being able to tweak the GH page URLs to point to the pages that correspond to what users are accessing in GHE rather than the official GH pages out on GitHub.com or the document links to point to our internal copies. Let me know if you'd like me to contribute back my local edits for review by the time.

Add 'clean repos' appendix

I think we should add a section to the appendix for use during train the trainer, with this following info. cc/ @githubtraining/trainers :

---

During the teach-backs for Train the Trainer, a participant currently needs to reset their class repositories so that they have a fresh copy from which to teach. For example:

Preparing repositories for Teachbacks

Project 1: Caption This

• First walkthrough activity
• Practice first merge conflict
  Please use this same class repository, apr-16, for the first project's activities.

Project 2: Merge conflicts

To prepare your local repository to be ready for teaching, use the following commands.

git checkout master
git reset --hard 1095c8c
git push --force
git checkout cb8731a
git checkout -b manual2
git push -u origin manual2
(open pull request)
git checkout 6b50ac7
git checkout -b css-changes2
git push -u origin css-changes2
(open pull request)
git checkout 945ca60
git checkout -b readme-update2
git push -u origin readme-update2
(open pull request)

Project 3: GitHub Games

• Edit the description to no longer be the correct URL
• In your own copy of GitHub Games:

git checkout master
git reset --hard 73c762c
git push --force

Project 4: Working locally

Create a new repository for these activities.

---

Class notes

Note - I'll come back later and create actual issues out of this. This is notes while I'm helping @mblack88 teach a class today 🎆

• Checking local git config seems oddly placed. Why don't we verify this in the getting started part?
• on 09_merging_pull_requests, there's the icon for merge, but why not use the button for new branch too?
• Going over the commit structure might be more helpful in the beginning... 😕
• Inside of reverting commits, might be helpful to do cherry pick right after. We started doing the revert from game_instructions and fixed inde.html to index.html. Then it was a nice moment to demo cherry pick from here to gh-pages. This was kind of by accident, but the opportunity seemed to flow better.

Add a listing of recommended tools for Git/GitHub Users

Prior to the re-design of services.github.com, we had a page that listed "recommended tools" for working with Git and GitHub. This page was actually an artifact of the old class-notes that has been hanging around for a while.

During the re-design, this page was 🔪 with the intent of finding a proper home for the information. We determined that one proper home was the training-manual itself.

Let's find an appropriate place to add these resources to the training manual during our next clean-up week.

Japanese PDF?

We have a Japanese translation for the training manual. Should we also make a PDF version of the Japanese manual available?

Add branch protection reg ex info

From a comment in Slack by @primetheus, pointed out by @ppremk 👍

In case anyone has customers asking how to deal with branch protection regular expressions: https://gist.github.com/primetheus/967242ccf3f848f9e5aeae9e785b5cb8

Rewrite PDF Generation to use something other than GitBook

I updated the instructions so that we can still use GitBook for the time being. #195

Here's a suggestion of a possible avenue for exploration suggested by @brianamarie in #193:

We could research additional options, like this docsify PDF converter package, that didn't exist at the time we worked with Git-Book

We should likely get this reworked before GitBook legacy is gone completely.

Release to open source: checklist

I'm going to share https://github.com/githubtraining/training-manual with the world. The following are items that we need to take care of to get this repository in shape for the open! @githubtraining/trainers, @beardofedu, @amyschoen, if you're able to help with any of these, that would be very helpful 🙇 (cc @matthewmccullough, @BonnieC)

Before we make this public, we need to complete the following:

Coordination

• The repo is visible to the teams below (typically all employees should have read access pre-open-source)
  • In progress: https://github.com/github/entitlements/pull/10424/
• Discuss with @github/legal if there are any licensing or other legal concerns.
  • In progress: https://github.com/github/open-source-releases/issues/120
• Discuss with @github/public-relations if it make sense to do any press around the release.
  • In progress: https://github.com/github/open-source-releases/issues/120
• Discuss with @github/marketing if it makes sense write about this project on the GitHub blog.
  • In progress: https://github.com/github/open-source-releases/issues/120
• Open an issue in github/creative to request a snazzy logo We have been using an image from the Octodex for this org and plan to continue with it

Preparation

• It has a name that is easy to remember, gives some idea what the project does, and does not conflict with an existing project or infringe on any trademarks.
• It uses consistent code conventions, clear function/method/variable names, and a sensible public API.
• The code is clearly commented, documenting intentions and edge cases.
• The distribution mechanism is as convenient, standard, and low-overhead as possible (RubyGems, Homebrew, Bower, Maven, NuGet, etc.).
• I have opened an issue in the oss-legal-review repo regarding how we use (or do not use) encryption in this repository. Please put a link to that issue in the comments on this issue.
  • In progress: https://github.com/github/oss-legal-review/issues/382
• There are no sensitive materials in the revision history, issues, or pull requests.
  • If any sensitive content or commit messages are found in commits, consider squashing the revision history.
  • If we wish to preserve sensitive history or we wish the public repo to have zero non-commit history, rename the private repo and create a new blank slate repo with the intended public name and any commit history intended to be public.
• It has a CONTRIBUTING.md based on this template.
  • In progress: #207
• [email protected] is provided as a maintainer contact (e.g., in the .gemspec email field for Ruby gems).
• It has a LICENSE; which one documented at licenses for GitHub open source projects.
  • In progress: #205
  • All dependencies (including transitive) are under compatible open source licenses (License Finder may be useful to do a spot check)
  • It is a library/will not be shipped as an application (eg desktop, mobile, or server package), or if it is, it is released with user-available license and credits information (desktop or mobile; see legal eagle) or includes license and credits information for a bill of materials (server; see licensed).
• It has a CODE_OF_CONDUCT.md; use http://contributor-covenant.org/version/1/4/code-of-conduct.md and fill in [email protected] as the email address.
  • In progress: #206
• It has a SECURITY.md; use https://github.com/actions/.github/blob/master/SECURITY.md or equivalent for the org it is being released in.
  • In progress: #210

README.md

• All in progress: #212
• It starts with a one-line description that explains what the project is about, who might be interested in it, what language its written in, and how it might be different from similar projects.
• It includes a list of features and limitations.
• It states the goals and scope of the project to help set expectations and filter proposed changes down the line.
• It includes the current status (e.g., proof of concept, used in production, active development, orphaned, etc.)
• It includes a description of the kind of environment required to run the software and instructions for setting it up.
• It clearly states the external dependencies and directions for installing them.
• It includes a high-level development roadmap or link to open issues/milestones.
• It explicitly asks for contributions, if you want them, with a link to CONTRIBUTING.md.
• It has a License section that states the license and if any GitHub logos are used, the line When using the GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).

Maintenance

• At least one Hubber is committed to managing community interactions by triaging and responding to issues, giving feedback and merging pull requests, and releasing new versions. This will be handled by the @githubtraining/programs team as a part of our existing comms duty.

Next steps

• Update the issue in the github/open-source-releases repository
• Make the repository public
• Change the name of the repository to github-training-manual
• Change the owner to github
• Implement redirection solution (create training-manual repository that links via README.md and gh-pages to the new manual?)
• Change the name

Confusing instructions for merge conflicts

During class with @ppremk, we found that several people had trouble understanding what my-branch meant while reading the instructions to resolve merge conflicts.

I'm not sure what the right way to portray the instructions is, but I think there's room for improvement. I'm opening this issue so it doesn't get forgotten - please feel free to jump in and fix @githubtraining/trainers, or @ppremk or I will get to it later.

Instructor scripts (exercises)

Is there any interest in capturing Instructor scripts/exercises that should be simple but convey a concept clearly? Or maybe these could be exercises left to the students?
Such as the following:

git diff exercise

This exercise will

• (1) show the students that a file may be in 3 local states at the same time and
• (2) will clarify which file (a) or (b) is referred to when git diff shows its output.

Setup:

$ mkdir show-difs
$ cd show-difs/
$ git init
$ echo "This file is in History" > file.md
$ git add file.md
$ git commit -m "added file.md"
$ echo "This file is in Staged" > file.md
$ git add file.md
$ echo "This file is in Working" > file.md

Show the results of git diffs

• Show the difference(s) between what's in Working and Staged
• file a is in Staged, file b is in Working

$ git diff
diff --git a/file.md b/file.md
index 4959ef4..860e405 100644
--- a/file.md
+++ b/file.md
@@ -1 +1 @@
-This file is in Staged
+This file is in Working

• Show the difference(s) between what's in Staged and History
• file a is in History, file b is in Staged

$ git diff --staged
diff --git a/file.md b/file.md
index 8ff44ce..4959ef4 100644
--- a/file.md
+++ b/file.md
@@ -1 +1 @@
-This file is in History
+This file is in Staged

• Show the difference(s) between what's in Working and History
• file a is in History, file b is in Working

$ git diff HEAD
diff --git a/file.md b/file.md
index 8ff44ce..860e405 100644
--- a/file.md
+++ b/file.md
@@ -1 +1 @@
-This file is in History
+This file is in Working

Check for available repo name immediately

When running option 1 in script/teach-class to create a new caption-this class repository, the availability of the repository name is not checked until after you're asked for the class dates and facilitator username. We should make this check happen immediately after entering the repo name to avoid having to play a guessing game.

Use Google Analytics

It'd be nice to get some metrics on the manual usage, as brought up in a retro for a prior engagement.

Improvements for sharing

• We have a cadence of making releases that would automatically be shared in the train the trainer slack

• We should either make the scripts/templates be within training-manual, or make it be a submodule

🎉 @githubtraining/trainers for later

Add more detailed instructions for setting up on GHE

We have a document that we've used internally for setting up on GHE, and I think it would make sense to include here.

Here's the raw text, that would need some editing to fit this situation.

# Setting Up GitHub for Developers Class on GHE

The following steps are designed to help admins set up the necessary accounts, repositories, and permissions to allow learners to complete GitHub's training classes on your organization's GitHub Enterprise instance.

## Step 1: Create Necessary Accounts

- Create an individual account named `githubteacher`. This is the account the trainer will use.
- Create an organization called `githubschool`. Githubteacher must be an admin in this organization.

## Step 2: Clone Template Repositories

Clone the following repositories from github.com:

https://github.com/githubtraining/caption-this
https://github.com/githubtraining/github-games
https://github.com/githubtraining/polygons

## Step 3: Push Template Repositories to GHE

1. Sign in as `githubteacher`
2. In the `githubschool` organization, create three new repositories with the same names as the ones you cloned above (`caption-this`, `github-games`, and `polygons`). **Do not choose the option to Initialize the repo with a README**
3. Copy the clone URLs provided for each repository to your clipboard.
4. From the command line, cd into each repository you cloned in step 2.
5. Type `git remote set-url origin GHE-URL`
  - Note: in the `polygons` reposoitory, you will need to checkout to each of the branches before you push. 
6. Type `git push --mirror origin`.
7. Please ensure the pushed repositories contain the appropriate branches (most have more than 1).

## Step 4: Set up GitHub pages

Several of our class repositories are published as [GitHub pages](https://pages.github.com/). Please [enable GitHub Pages on your GHE instance](https://help.github.com/enterprise/2.12/admin/guides/installation/configuring-github-enterprise-pages/).

## Step 5: Invite Participant collaboratores to `caption-this`

We will collaborate on the `caption-this` repository in class. Please gather the GHE usernames of each class participant and invite them as collaborators to the `caption-this` repository.  You may find it easier to create a team in the new org, and invite individuals to that team. This will allow you to grant access to newly created repos in the future. 

>Note: this is only necessary for the `caption-this` repository, as we will fork the other repositories. 

If anyone would like to tackle this before I can get to it, please feel free!

SOS: merged pages are causing build failures!

🆘Help please, @githubtraining/trainers @JasonEtco!

The builds on gh-pages are currently failing.

Can anyone help figure this out? The builds in PRs all work fine, and all other builds on master work fine according to Circle and locally.

@beardofedu and I will be teaching with new content (currently NOT available on the site) tomorrow. @crichID @hollenberry @JasonEtco could you please assist in helping get this content served on githubtraining.github.io/training-manual?

CircleCI 2.0

Hey @brianamarie I got this email today:

July 2017 Updates
In this issue: CircleCI 2.0 now generally available, manual approvals with Workflows, surface your slowest tests on Insights, how-to guides, and more. 

More power, control, and flexibility: CircleCI 2.0 is out of beta!
Today we released CircleCI 2.0. Our new platform offers more power, flexibility, and control. You now have access to first-class support for Docker (including layer caching), Workflows for customizable build pipelines, flexible resource allocation, and more.  

A huge thank you to our customers who ran 1M+ builds on CircleCI 2.0 during our beta period. CircleCI 2.0 is out of beta, but we're not done delivering new features: expect 2.0 for behind-the-firewall builds and macOS soon. What else do you want to see? Let us know here. Liking CircleCI? Add us to your stack on StackShare and see what our stack looks like.   

New: Manual approvals with Workflows 
You can now configure Workflows to pause until you manually approve a job before continuing to the next job of the workflow. Last month, we released Workflows on CircleCI 2.0 which recognizes your build, test, and deploy stages as individual jobs. With manual approvals, you have even more control with each stage of your development process from start to finish. Learn more about how this works on CircleCI 2.0.  

Get the most out of your tests. Use Insights to discover flaky, slow, and failed tests 
Find weak spots in your test suite and mitigate the worst offenders. You can now view failed tests, slowest failed tests, and success rates for builds on a branch using CircleCI Insights. Learn more here.  

Success Rate 

How-to: Set up tricky containers in CircleCI 2.0 multi-image 
Here's a helpful guide offering some tips on how to handle third-party containers that can be tricky to work with on CircleCI 2.0. 

How-to: Build, test, and publish Snap packages using Snapcraft 
Snapcraft, the package management system, reimagines how you can deliver software. A new set of cross-distribution tools are available to help you build and publish "Snaps". This guide covers how to use CircleCI 2.0 to power this process and some potential a-ha moments along the way. 

Language Spotlight: The missing guide to Elixir  
CircleCI success engineer Zachary Scott takes us through his  introduction to Elixir, a dynamic, functional language built on Erlang VM that shares many of the same philosophies as Clojure, CircleCI's language of choice.  

In case you missed it: 
* Workflows on CircleCI 2.0 gives teams granular control over jobs and form complex, end-to-end flows 

* A top requested feature was released: Import project environment variables

* Top features and learnings from WWDC17 along with other updates for macOS and iOS developers 

* Why we don't do whiteboard interviews at CircleCI 

Thanks! 
The CircleCI Team 

Do you want me to test our class against the new UI, or is this something you already did during the development of the course?

Add appendix section: classroom facilitation tips

While this guide is awesome, let's make it even easier for the trainers to be 💪!

I'd like to have a section on facilitation/general teacher tips:

• Suggestions for keeping the class on track (i.e. time management techniques)
• Setting up logistics in the beginning (e.g. in the event students are training at a building/site they aren't typically at, where does stuff like the bathroom and 🍕 exist?)
• Have a method to capture off topic ideas/questions (e.g. parking lot)
• Techniques for keeping the class engaged when they take a moment to visit ☁️ ☁️ ☁️
• Links out to resources (let's not recreate the wheel)

I'm sure there's more that I'll think of as going through this. Feel free to make suggestions!

Add CODEOWNERS information

The 2.11 release of GitHub Enterprise brought CODEOWNERS to the center stage. This is something we get a lot of questions about in class, so we want to cover it.

Existing documentation:

• Codeowners help docs
• Introducing Code Owners (Blog post)

@githubtraining/trainers Do you think this would be best to include as a:

• 👍 New activity
• ❤️ Mentioned feature in Getting Started where we call out other important files
• 🎉 Mentioned optional feature/activity combo in an appendix

@githubtraining/trainers Please emoji vote soon, and let me know if you have any questions. 🎈

Add Content to Training on GitHub Desktop 2.0 Rebase and Stashing Feature

During the All Hands today, the GitHub Desktop Team announced a data driven statistic collected on the usage for the mentioned features. It would be beneficial to consider including some content on this as part of our standard curriculum for GH4D training offering.

As discussed in slack

cc/ @hollenberry @brianamarie @beardofedu @allthedoll @rwnfoo @aharshbe

Conflict script not creating a new repo

When running the script to create a conflict repo, the repo is not generated for the provider.
cc @githubtraining/implementation-engineers

Considering the name and org of this repository

Name and org of this repository

As we work to open source this manual #202, now is a good time to consider the ownership and title of this repository. Any changes we make would include some effort to make sure things are done right, but it makes sense to open source this content in the right way.

We've decided to move and rename this repository from githubtraining/training-manual to github/github-training-manual.

Here's what needs to happen to make this work:

• Prep work:
• Open pull request addressing hard coded URLs #232
• Open pull request addressing redirect #231
• Create repository page linking to all manuals https://github.github.com/training/
• Configure redirect from training.github.com to https://github.github.com/training/
• All at once:
  • Move this repository to github org
  • Rename this repository to github-training-manual
  • Switch the repository to public
  • Merge the PR for hard coded URLs
  • Merge the PR for redirect

Contents of post originally

Org considerations

githubtraining vs github

githubtraining 😀

Historically, this was the easiest place for this type of content because of access management. We could easily add partners or customers to this repository without fearing we were giving "too much" access. Now, there is no difference in access management. Open sourcing this repository will do most of the work there for us, regardless of the org.

• 👍 Pro: Easier installation of 3rd party apps (if needed)
• ?

github 🎉

• 👍 Pro: Brand recognition, credibility, unified message
• 👎 Con: Historical links would break
• ?

Name

training-manual vs github-for-developers-manual

training-manual 👀

It's what it's always been called.

• 👎 Con: It's vague when we consider our growing materials for other content topics
• ?

github-for-developers-manual 🚀

• 👍 Pro: It's more specific to the content
• 👎 Con: Historical links would break
• ?

Next steps

@githubtraining/githubbers @githubtraining/trainers @matthewmccullough @dcdrennen @jonlipsky @AaronKowall @amyschoen Thoughts? Are there other pros/cons that aren't considered here? Please comment below with any additional thoughts, and/or react with opinions to this original post with the emojis by the different options above.

Small manual fixes

@githubtraining/trainers 👋 I'm opening this issue after being on site for a Train the Trainer. I want to document these things, so even if I can't fix them immediately, they don't become lost. I think these would fit well in a "cleanup week" unless someone has bandwidth to tackle them separately.

• Add to merge conflict activity, some kind of review where others will be involved in giving instruction on how to resolve conflict 8c413bc
• In git log, note that the decorate behavior is already default on git bash 0334962
• Add link to git-scm on git log section a81280b
• Change git co alias - this alias exists in SVN and means something different 07df8f0
• Git bisect = {: .warning} is rendering ac66ac7
• Git bisect = typo in instruction #3, sha is missing the ">" 524d0fd
• Note that you could also use "cmd //c tree" to use Windows' tree

Update README in template repo to remove emoji after facilitator name

The microphone emoji is messing up the script for creating class repositories. It should be removed from

• services-training
• the template repository in this org

Improve scripts for creating repositories

It would be ✨ if the conflict practice script would also:

• First check for a repo on the teacher's account, then delete it if necessary #113
• Create a merge conflict within the class repository so we could easily demo it first one time before sending students off on their own to do the activity

Edit: I also have noticed a few things to update in our template repository:

• The new octocat images are so large, that we can't always see the text. Could we move the text to be above the image?
• One of the octocats doesn't work. It references this image: https://octodex.github.com/electrocat.png
  

Noting here to tackle later, cc @githubtraining/trainers

Multiple invitations sent via script

I've consistently had trouble during class where the script sends multiple invitations, inconsistently. Sometimes users get one invite, sometimes two, and sometimes three.

Does anyone else have this issue? Does anyone know why this might be happening?

cc @githubtraining/trainers

Add tags and releases to the training manual

These topics come up frequently but are not currently covered in the training manual. Let's add them!

Feedback please: Code quality checks of scripts

Running shellcheck to check the code quality of the scripts in the script directory result in over 580 code quality issues across 12 scripts. These issues can have unintended consequences that will result in problems with the execution of the various scripts.

test.txt
(rename test.txt to test or test.bash, make executable, run; requires shellcheck - See https://github.com/koalaman/shellcheck)

I'm willing to undertake this issue and resolve the code quality issues if it is considered valuable.

Feedback please.

small manual fixes - Japanese and English

@brianamarie

The GitHub JP Support team helped me to review the Training Guide to assess the translation quality, Here are their comments:

I've gone through the training and this is awesome. As Hayato said, the translation quality is good and I have nothing to add except these tiny items.

1. The welcome page isn't translated yet?
2. There are both Pull Requests and Pull requests - should be consistent
3. This isn't a translation issue but the word named is displayed in the "code formatting" instead of normal text in the original 06_working_locally.html page, there is:

"Find your file, named 2010-02-##-USERNAME.md."

Should it be

"Find your file, named 2010-02-##-USERNAME.md."

If so, the Japanese version should be updated as well. For example,

あなたのファイル、named 2010-02-##-USERNAME.mdを見つけます。

Can be

あなたのファイル、2010-02-##-USERNAME.mdを見つけます。

Again, thanks for the great job 🙇

Also, let me know if there is interest in getting the Welcome page translated as well.

Thanks

Alexandra

Visuals for 'understanding the .yml' file

As discussed at the Hack House, the manual doesn't have much in the way of visuals for explaining CI/CD. @JasonEtco @crichID What are your thoughts on coming up with something to fill this gap? I'm thinking something like this:

But, you know...different and better. 😉

Git Internals Graphics Update

Hey @JasonEtco !

I was looking through the graphics changes and noticed this:

Do you think this image is better without the arrows? I think they might help make the relationship between commits more clear.

Sane defaults for Git

When users download Git on Windows (may also be true on Mac, but haven't tested), the defaults will prompt them to do things like set line endings and the credential manager. This is fine if they are using their own PC, but we should warn people if they are using loaners.

Let's add this to the set up section.

Update README in script folder

The script folder needs an updated README. Many of the steps outlined there are now automated by the scripts.

Add submodule and other advanced information

Does it make sense to put some advanced content outlines in the manual or in this repository?

cc @githubtraining/trainers

• @brianamarie

---

GitHub for Developers - Day 2 for Advanced Audiences

This outline is a more advanced version of GitHub for Developers day 2 and should only be used if you have finished all of the day 1 material, both merge conflicts in the github-games activity (including using a second remote to pull in the merge conflict on the second activity), git bisect and git revert on the first day of training.

Morning Warm-Up

Step 1

• Find a partner to work with
• Add your partner as a collaborator to your copy of the github-games repository.
• Clone your partner's repository to your local machine.
• Use git clone URL repo-name to give the repository a different name
• Create a branch called partner-instructions in your partner's repo.
• Add instructions for playing the game (beginning at line 7) to the README.md
• Push your branch to your partner's repo and open a pull request.

Step 2

After your partner has completed step 1:

• Go back to your copy of the game and merge the game-instructions branch in your own repo (you can use a pull request or do it locally).
• Go to the pull request your partner created and resolve any merge conflicts in your own repo.

Creating Atomic commits

• Why Atomic commits are important
• Making Changes
  • Create a branch for git checkout -b slow-down
  • Change the timing for the game to speed it up or slow it down in index.html (line 78)
  • Change location of texture.jpg to images/texture.jpg (line 9)
  • git status
  • mkdir images
  • git mv texture.jpg images/texture.jpg
  • git status
  • git add -p and stage the change for the image location
• Viewing Local Diffs
  • Comparing Local File States
    • git diff
    • git diff --staged
    • git diff HEAD
    • git diff --color-words
• git commit
• git status
• git commit -am

How Commits are Made

• Show how commits are made and the impact it has on what we can do with our history.

Creating a Repository Locally

• Creating a Repository on the Command Line
  • git init practice-repo
  • ls -al
  • Show tree .git directory
  • Show cat .git/HEAD
  • Show cat .git/refs/heads/master
  • Show objects directory (currently empty)
  • touch README.md
  • Show tree .git again, still no objects
  • git add README.md
  • Show tree .git again, you now have 1 object, this is the blob
  • git commit -m "Initializing the repo with a README"
  • Show tree .git, now you have a tree object and a commit object
  • explain the importance of the root commit
• Use script to add files for reset activity (it is helpful to add this to the day 1 class repo):
• Bash: for d in {1..6}; do touch file$d.md; git add file$d.md; git commit -m "adding file $d"; done
• PowerShell: for ($d=1; $d -le 6;$d++) { touch file$d.md; git add file$d.md; git commit -m "adding file$d.md";}

Resetting History

• What happens when you reset - which trees are overwritten by each of the reset modes?
• Git reset modes - where the changes land
• Demo soft reset
• When is this commonly used?
• Demo mixed reset
• This is also the command we use to unstage files
• Demo hard reset
• Anything in your working directory or staging area will also be over-written - the only exception is the untracked files

Git reflog

• Show git reflog
• Caveats of reflog
• Local only
• Temporary (90 days for reachable commits, 30 days for unreachable commits)
• Show git cherry-pick of single commit
• Show git reset --hard back to where file 6 was originally created
• Point out the effects of resetting forward on commit IDs

Rebase

• Set Up:
• Reset back to initial commit
• Create a branch git checkout -b rebase-me
• Cherry-pick files 4-6 (out of order) onto the new branch
• Checkout to master
• Cherry-pick files 1-3 (in order) onto master
• Discuss Merge Strategies (if you haven't already)
• What type of merge is this? Recursive
• What if I want to do a fast forward? I would need to Rebase
• What happens when we Rebase
• Checkout to rebase-me branch
• git rebase -i master
• Reorder files 4-6 on the branch
• Finish the rebase
• Merge rebase-me into master

Rebase with conflicts

• Create a new branch called rebase-conflict
• On this branch echo "This is some awesome content for file 4" >> file4.md
• git checkout master
• On this branch echo "File 4 already has some awesome content, but I like conflict" >> file4.md
• git checkout rebase-conflict
• git rebase master
• Now you will have a conflict, fix it just like you would a regular merge conflict (open the file, fix the conflicts, do a git add)
• git status
• git rebase --continue

Resets with Merge commits

• More complex resets
• Resetting when there is a merge commit involved
• git reset --hard HEAD~^
• git reset --hard HEAD~^2 - tells git to reset along the 2nd parent

Amending Commits

• commit --amend
• Amends the commit at HEAD
• Show amending the commit message
• Show amending the commit content (anything in the staging area will be added to the last commit)

More fun with branches

• Oops, I forgot to create a branch
  • Modify file before creating branch
    • Show that the working directory and staging area are portable - files sitting in each area will remain there when you switch branches
• Octopus Merges
• Create 2-3 branches off of master - on these files, add some .txt files to set up for the filter branch scenario
• git checkout master
• git merge branch1 branch2
• Git will merge all of these branches together
• Delete the extra branches

Filter branch

• What is Filter branch? When is it used?

• This is never something that is done lightly.

• This is typically a conversation with your entire team.

• One person makes the changes

• They will need to push --force to update the remote

• Everyone else will do a fresh clone of the repo

• If you pushed your secrets to GitHub, get new secrets

• Use filter-branch to remove the .txt files you added earlier

  • git filter-branch --tree-filter 'rm -f *.txt' HEAD

• Show the back-up branch created by git refs/original/refs/heads/master

• After you have verified master

  • git update-ref -d refs/original/refs/heads/master
  • git reflog expire --expire=now --all && git gc --prune=now

• Show BFG Repo Cleaner and discuss the difference

Tags and Releases

• Introduce Tags
• What are they? Pointers to a specific commits
• Two types -a (annotated) and lightweight
• Using semantic versioning
• When to use Tags
• Difference between a tag (Git) and a release (GitHub)
• Create git tag -a v1.0 SHA
• git lol to show tag pointer
• Show how to view the tag and its contents
• git show v1.0
• Show how to check out to tag
• git checkout v1.0
• Explain detached head state, what does it mean?
• Show cat .git/HEAD
• If you add commits here, what happens?
• git checkout -b new-branch
• Show how to create a branch from a tag
• git checkout -b new-branch v1.0
• Pushing tags
• Tags created locally are not automatically pushed
• git push --tags
• Show how a tag is created on GitHub

Submodules

• Discuss the most common uses of Submodules
• Discuss better ways to accomplish dependencies

Add the submodule to the repository

• Use the repository for day 1, ask everyone to watch while you add the submodule to the repo
• git submodule add https://github.com/githubtraining/example-submodule.git
• Show git status
• cat .gitmodules
• tree .git to show that the .git of the submodule has been added to the .git of the primary repo
• git diff --cached to show the content of example-submodule which should just be the sha of the current master in that branch
• commit the submodule and push

Show the submodule on GitHub

• Point out the submodule in the repo
• Show the cross linking and SHA reference

Working with repo with Submodules

• Clone the repo to a new directory to demonstrate the following
• Ask the class to do a git pull
• The submodule directory is there, but it doesn't have anything in it
• git submodule init
• git submodule update
• Can also do git clone --recursive URL to handle this during the clone
• Or, git submodule update --init
• now you can cd into the repo and see the contents
• Notice the detached head state - you can checkout to any version of the repo (e.g. a tag or another branch) and commit that change in the primary

Workflows for making changes in Submodules

• Git gives you the ability to make changes to submodules from within the parent repo.
• cd into the repo; note that you are still in a detached head state
• Create a branch
• Make and commit changes
• git push --recurse-submodules=on-demand

Submodule Scripts

• We script a lot of the common submodules actions within our repository so people don't need to remember multiple steps
• Show example in services-web

Scripts to rule them all

• Bootstrap scripts for submodules
• git submodule sync --quiet --recursive
  • Looks at the .gitmodules file and makes sure the URL listed for the submodule still matches what is in your local .git. If not, it updates it.
  • --recursive tells Git to also update any nested submodules.
• git submodule update --init --recursive
  • Clones missing submodules and pulls down the most recent changes. This would be the same as cding into the submodule and typing git pull.
  • --init also initializes any submodules that have not previously been initialized locally. In other words, it takes the information from .gitmodules and uses it to create a home for the submodule in .git/modules
  • --recursive tells Git to also update any nested submodules.
• Adding these scripts to the bootstrap or similar script ensures that tests or builds run against the repository are always working with the expected version of the submodule.

Feedback: First Run of CircleCI Class

Notes

• Please change CircleCI spelling to "CircleCI" with no space <-- issue opened by CircleCI folks in class (PR #60 )
• For the section on What is CI/CD, the CircleCI team actually created a great video that can help us with this section: https://youtu.be/wliXoh8OL-c
• In setting up CI/CD, this is where the trouble started 😉
  • Most students couldn't see the githubschool org as an option for selecting the project
  • There were 2 public keys created, one slightburne and jennieohyoung. By some quirk of fate, they were both members of the githubschool org (I'm guessing this was the result of their participation in other activities)
  • I tried to add the other students to the githubschool team in CircleCI, but got the spinning wheel of death (not even sure this would have helped, but I was going to try it 😉)
  • We ended up forking everyone's copy of the game to their personal account and working from there
  • This worked for most users, but a couple had to also go in the project settings under Build>Advanced and enable builds on forks ??
  • Potential solution, we could create a team with all class members in the githubschool org, however, I think we may still encounter the issue with queued builds because I think all of the builds are technically running on the githubschool org and not on the individual class member accounts. We will need to test this!
• In merging tests, there is an error in the manual, step 1 (looking at remote tracking branches) should be removed. @brianamarie #59
• On the circle-tests branch, the package.json still contains "test": "./node_modules/jshint/bin/jshint stats.js". This caused our npm tests to fail due to "errors" in the stats.js file. We will need to fix this branch to avoid this in the future. Done in this commit
• In the section on interacting with CI/CD we need to instruct the learner to turn on GitHub pages. We also need to make sure they know the correct URL. (#63 )
• Currently, the verify URL test is only reading the project name and not paying attention to the repository owner. We should fix this.
• Also in interacting with CI/CD, we should remove the step about running the tests locally from the main steps and only include it as a note. @brianamarie #59
• We did all of the steps in Interacting with CI/CD from the UI 😉
• The end of day 3 needs homework 🎉 I had them go ahead and modify the circle.yml to add the remaining tests.
• We need to update the Circle section to use 2.0!

That's it for Day 3, tomorrow is a new adventure!

/cc @beardofedu @brianamarie @hectorsector @hollenberry

GitHub Pages build error: invalid post date

I recently ran into the following issue in a caption-this repository with over 30 students:

Here's what the help docs say about this error:

Invalid post date

This error means that a post on your site contains an invalid date in the filename or YAML front matter.

To troubleshoot, make sure all dates are formatted as YYYY-MM-DD HH:MM:SS for UTC and are actual calendar dates. To specify a time zone with an offset from UTC, use the format YYYY-MM-DD HH:MM:SS +/-TTTT, like 2014-04-18 11:30:00 +0800.

If you specify a date format in your _config.yml file, make sure the format is correct.

The way we are generating files does not account for situations where the number of files in the _posts directory is greater than 31, the number of days in the month of January.

training-manual/script/create-files

Line 114 in be3f90a

echo "Time to create file 0000-01-$FILE_NUM-$STUDENT.md in $COLLAB_REPO"

One file named 0000-01-01-intro.md is part of the caption-this template repo, so a maximum of 30 new post files can be created by the create-files script before we run into this build error.

We need to modify the script to increment the month. We could make this simple by incrementing after each 28th post (since 28 is the minimum number of days in a month) so we don't need to account for the varying number of days in each month.

/cc: @githubtraining/implementation-engineers

Improve deployment pipeline

When we first set up the training manual, it didn’t have others properties like the training scripts. The current pipeline is GitHub > Circle > Deploy everything to GH Pages. The deployment to GH Pages particularly concerns me because it relies on a gh-pages branch with history that deviates from master.

We’re older and wiser now, and it’s clean up week, so I’d like to clean this up. Some ideas I have are:

• improve/add Circle tests (they’re pretty much nonexistent right now)
• limit GitHub Pages deployment to just the manual
• look into proper use of GitHub Pages so we can deploy branches and test changes to the manual
• alternative to ☝️, explore using a Heroku pipeline with Review Apps

Remove any {facilitator} tags

Originally found and fixed in another repository, there are still several instances of facilitator tags from legacy versions that rendered this manual.

cc @githubtraining/trainers

Slight wording change?

I wanted to get some opinions on this before going ahead and doing a PR. I got some help proofreading my version of the guide for my upcoming class, and I got a suggestion on 02_getting_started.

In the "Snapshots, not Deltas section", snapshots of repos are defined as being commits. The reader thought it would provide more clarity to reword

When you create a new branch in Git, you are actually just creating a pointer that corresponds to the most recent snapshot in a line of work. Git keeps the snapshots for each branch separate until you explicitly tell it to merge those snapshots into the main line of work.

to

When you create a new branch in Git, you are actually just creating a pointer that corresponds to the most recent commit in a line of work. Git keeps the commits for each branch separate until you explicitly tell it to merge those commits into the main line of work.

in the "Branches are Lightweight and Cheap" section. Let me know what you think. I'll make the edits and submit a PR if folks think this is a good modification. Otherwise, feel free to close out this issue.

GitBook is being deprecated

I'm working on setting up a new laptop, and I noticed the GitBook link on the main README.md no longer resolves.

https://toolchain.gitbook.com/ebook.html

In digging in, it looks like they're deprecating the CLI version we use to generate the PDFs and moving to a cloud solution instead.

https://docs.gitbook.com/resources/gitbook-legacy
https://docs.gitbook.com/resources/gitbook-legacy/v2-differences

Are there any plans to use this integration which looks like it gets installed on the repo instead? I'm guessing it's not going to be an option for those of us teaching against our local GHE instances, so we might need a plan B there. Unfortunately, it looks like they're also going to a paid plan.

https://docs.gitbook.com/pricing/plans

CC @githubtraining/trainers

New Training Manual Graphics

I've done a run through of the courses (mostly GitHub for Developers) and have picked out a few areas that could use new graphics. Your suggestions are also in this list ✨

- Forks
- Multiple Repositories
- git bisect
- Difference between origin/upstream
- Difference between forks/branch/clone
- Resolving Merge Conflicts
- Merging Pull Requests

I'll be tackling these in a PR, but if you have any other suggestions please let me know. Also note that this is entitled New Graphics; if there are existing images that you think could be clearer, I think a separate issue would be best.

cc @githubtraining/trainers for 👀

Broken link

@brianamarie, looks like I'm a bad reviewer. The one link I tried here doesn't work:

https://github.com/githubtraining/training-manual/blob/master/docs/app_authentication.md

https://help.github.com/desktop/faq/articles/can-i-log-in-behind-a-proxy-server/

Thank you to Mehul Shah on our training team for noticing when I tried to merge this into our local copy of the guide.

Linter has problems with our headers

The linter running on pull requests currently has problems with our headers.

Is there a way to de-select certain linting features for Markdown, so that we are able to keep some styles that we like without losing other benefits of the linter?

cc @githubtraining/trainers @admiralAwkbar

Changes to repo generation for students

I just want to give everyone a heads up that I'm working on this. We had some fun with DST and latecomers to class this morning. Getting this going in our GHE instance and then I'll get it merged into the official scripts. Here's a high-level list of what all is included. I'll update this with more info if I find anything else.

• Changing up the permissions to add everyone who comments as a repo collaborator.
• Fixing up the logic around detecting if a user is included or not. It's either busted or changing up the collaborator logic broke it. I also renamed containsElement to containsCollab to make it more obvious on what's being tested.
• Basing the user adds on the direct collaborators rather than every collaborator that is inherited from org permissions.
• Fixing up the numbering scheme so it picks up where it left off on subsequent runs rather than starting over at 2 again.
• Making the teacher always the second post.
• Students are now being properly added to the list for Activity 1 (Issue 2 in class repo).
• The teach-class script now prompts if you want to make the class repo private on everyone run instead of only prompting the first time.
• Changing up the other repos that are generated to use the direct collaborators as well.