Git, Markdown, and GitHub for Designers

Why?

Why Git?

Git solves several problems software developers have, and it has been doing so since 2005. Three main ones are:

• I need to be able to save my code as it exists, before I change it
• Me and my team need to be able to work on different features simultaneously
• We need to be able to combine those features when they're ready

Git solves these problems as a Version Control System (VCS). There are a lot of them, but most folks use git.

Commits

Save points in Git are called commits. You select which changes you want to save (on a per line basis) and add a note (a commit message). From here you can keep working and if you ever have an issue, you can always return back to the point you committed.

Branches

You can think of branches as lines of work. Git starts with one called main that you can think of as the trunk. From there if you create a new branch, it remembers all the work from the main branch and you can work on new features, adding commits without affecting the main branch. This lets developers work in parallel on different efforts.

Merging

When a feature is done, developers combine their branch into the main branch via a merge. This is a special commit that combines the changes on your branch with any on the main branch, saving them to the main branch. You also have the option to do a commit message on a merge, which you should do! You may also see this combining of branches called squash and merge or rebase. The distinctions here don't matter for your purposes.

The vast majority of the time, Git is smart enough to do these merges automatically. Sometimes, if two developers touched the same line in the same file, or moved and edited the same file, you can get a merge conflict. When this happens the later developer just opens the indicated file, looks are the two different changes, and sorts out the final input. Sometimes they check with the other developer if the changes aren't obvious.

Why Markdown?

Markdown solves one big problem for developers (and others!): I want clear, simple formatting on my text files that won't break from one platform to another! Being able to type in a text editor on my computer, and paste it into slack for review, and then into GitHub for publishing is a lot easier if I don't have to redo WYSIWYG formatting every time.

As a bonus, Markdown is easily typed via keyboard input only, and is also considered very readable in its raw format

# Important main header!
## Subheader

Sentence with **emphasis** and some _other emphasis_

 - basic
 - bullets

 1. numbered
 1. bullets

An embedded `code snippet`

Why GitHub?

GitHub solves two problems for developers:

• a single, central, cloud Git where all the developers refer to and work from
• facilitates code reviews via Pull Requests

Central workspace

Git doesn't require one main reference point, but it works a lot better if everyone agrees that this server has the primary copy. For us, GitHub is that main point of reference. We handle all the merges into main here.

Pull Requests

These are an innovation GitHub created where you can review all the changes prior to doing a git merge into the main branch.

Why are they called that

In git you push things to other servers. But that's a bit rude to do if you don't have a review of your changes yet! So the pull request is a middle step where you've pushed your code to GitHub, and you're asking another person to review and then finish the merge by pulling your code into main on GitHub.

What does this have to do with me, a Designer/Researcher?

Git

You really only need to work with Git through GitHub, unless you are actively interested in doing otherwise. I'll show you what it looks like on the command line at the end, if we have time!

If you're really interested in Git on the command line, here is an introduction and here is literally the whole book on it

Markdown

Markdown is how GitHub formats its wiki pages and how developers tend to take notes, so it's useful to know. You might even end up liking it enough to use it on your own!

Markdown exists outside of and beyond GitHub. It is a formatting syntax akin to HTML or LaTeX. Some favorite markdown editors of mine are HackMD.io and StackEdit, which let you edit and view a document side-by-side, giving the best of both worlds for portability and WYSIWYG.

Let's walk through Markdown as it exists in GitHub

GitHub

The main thing GitHub does for designers on Caseflow is allow you to version control and review your research documents, much like the developers do with code!

Create a Pull Request

The process looks (something) like:

• create or edit an existing file in the design repo, using markdown format.
  • you can even do this outside GitHub and paste your changed text back in! Markdown! 🎉
• scroll on down to the bottom and add a short commit message
  • the extended description is optional, but always add a message!
• Select the option `

  Create a new branch for this commit and start a pull request.

• optionally, give the branch a memorable name. developers tend to follow name/issueNum_short_desc
• Click Propose file change

Your changes have been saved to that branch and you are now dropped into creating a pull request! It can be a little intimidating, but worry not, it's only a few steps.

• Your commit message from the last screen pre-populates into the title. Feel free to make it clearer & more verbose, as needed.
• Add a longer message about what the change is for in the body.
  • For engineering changes we tend to describe what the issue was, what we did, how it affects end users and other developers, etc.
  • I suspect for design purposes you'll focus much more on the the research ask being answered.
• Over on the right you should assign the pull request to yourself, and then tag anyone you want to take a look at the work as a Reviewer.
  • these steps can also be done after creation, but I tend to forget, personally, if I don't do it here
• Hit Create Pull Request

That's it, you have a pull request! On engineering we tend to share the URL and tag our reviewers in slack, as well.

Review a Pull Request

If you get asked to review a pull request, go to the PR and look it over!

You'll find four tabs on a pull request, Conversation, Commits, Checks, Files changed. You only care about the first and last one.

Conversation

The description the author wrote up and any comments folks make show up here. Start here to get some bearings and context for what you're reviewing.

Files changed

This is the actual content that will go into the repository.

For Markdown files, you can choose to see them either as source diff (the exact text with markdown) or as a rich diff (how GitHub will display it after converting the markdown).

You can leave comments in source diff mode on any line by clicking on the blue plus on the line and typing in the text box. If you hit add single comment it posts immediately. If you hit Start a review if collects them all until you submit the review (keep reading!).

Submitting the Review

To submit a review you hit the green Review Changes button in the upper right on the Files changed tab. You can add a high-level message here as well. I like celebratory emoji. 🎉 💅 🆒

You can submit a review with three different states: Comment - just leaves all your comments, Approved - posts any comments and marks the whole thing as approved, and Request Changes - posts any comments and explicitly asks for more work to be done.

These states can either be just for you all, or GitHub can do special things with them. For example, on the main Caseflow repo a PR cannot be merged without at least one Approved review.

A final note: Be extra kind and considerate on reviews. It can be very hard to receive feedback under any circumstance, and doubly so when text based. Taking the extra time to add thoughtful wording or extra emoji can make a huge difference in how that feedback feeds.

Merging a Pull Request

After you've gotten all the feedback wanted or needed on a PR, you need to merge it into the main branch! Head to the Conversation tab and scroll to the bottom.

Getting your branch up to date

If you see the message This branch is out-of-date with the base branch and a button labelled Update branch, that means other folks have changed the main branch since you split off from it. Go ahead and hit that button. If you get any result other than that alert disappearing, ask a developer for help! Most likely you'll just need to resolve you and another designer changing the same file.

Merge!

Everyone on board and your branch up to date? Hurray! Hit the Merge pull request button. Add a short, informative message here and hit the final button. You're done! The pull request will mark itself as merged. You can delete your branch as prompted (as the changes are now in main) and close out any related issue.

Additional References

Github has wonderful documentation. Here's the official info about pull requests, how to review them and how to merge them.

If you want to work with GitHub documents locally, you can also checkout GitHub Desktop. This lets you manage editing the files locally in any editor and then handling the commits in the app. You will need to understand pulling and pushing with git to sync to use this, but it's a great additional option if you want it!