This session will be recorded

Git & Github

An introduction

Eric Eggert

W3C/WAI

ee@w3.org

w3.org/People/Yatil

Note

Different editors have different preferences for using Github. Please talk to the editor of the delivery you want to contribute to.

Contributions

welcome!

Git

„Git is a distributed revision control system with an emphasis on speed, data integrity, and support for distributed, non-linear workflows.“

http://www.git-tower.com/learn/git/ebook/command-line/basics/what-is-version-control

Repository

Stores all versions and associated metadata for the project

Local & Remote Repositories

In Git, every computer has a complete copy of the repository (Local Repositories)

 

All changes can then be synced to a central remote repository

Commit

A Commit is a specific set of changes that is submitted to the repository, creating a new version (of the committed files)

 

each commit has a “commit message” that describes what was archived with this commit

Branches

Branches

  1. Easy to create
  2. helps to concentrate on one change
  3. can later be merged into the “main” branch
  4. avoids collisions from multiple editors

no need for CLI

Source tree

Mac & Windows

Github for Windows

Windows

Github for Mac

Mac

Github

A GUI for Remote Repositories

C

provides other project management helpers,

such as:

Issue management

Wiki

Milestones

Each delivery has its own repository

For example:

  • github.com/w3c/wai-tutorials/
  • github.com/w3c/wai-quick-start/
  • github.com/w3c/wai-wcag-quickref/

Edit Files

    Github

O

All kinds of file types

  • HTML
  • CSS/SASS/…
  • JavaScript
  • PHP/Ruby/Python/…
  • Markdown
    (Also w/ YAML FRONTMATTER)

ISSUES

Pull requests

Reference syntax

  • @username – notifies a user about a comment
    (Pretty much like @-replies on Twitter)
  • #123 – References that issue
  • 6f8bddc011 – references that commit

Github flavored Markdown

When to use what?!

Issues

  • General feedback
  • Discussing passages of documents
  • collecting opinions

Writing
“good”
Issues

Always provide a link to the page in question

Or, if possible, a link to the section of the page

Keep the issue clear, concise and focused on a specific issue

Bad: “I don’t like content of page X”

 

good: “On page X the wording in the introduction is unclear.”

Pull requests

  • Concrete text/code proposals
  • implementing changes that have already been discussed
  • Typos & grammar corrections

creating
“good”
pull requests

Make “atomar” changes

  • If there are multiple, independent wording changes, create multiple pull requests
  • if it’s a change throughout a page (or repository), one pull request is enough

Github workflow

Create branch

Github workflow

Commit changes

Github workflow

Open a pull request

Github workflow

Discuss and (optionally) add more commits

Github workflow

Merge

Made with Slides.com