IETF Git and GitHub Tutorial
This page is meant to help IETF contributors new to Git start using GitHub.
Disclaimer
This page is work-in-progress. Please see the document’s repository and file an issue or submit a Pull Request with any suggestions for improvement!
Introduction
GitHub and similar version control systems used for developing IETF Internet Drafts and managing Working Group process in a transparent fashion can be highly effective. GitHub in particular enables several different modes of interaction for Working Groups and its participants, as discussed in the Using GitHub draft. However, using these systems without any prior experience may be challenging.
This document serves as a tutorial for GitHub and its underlying concepts. It provides instructions for interacting with GitHub for the purposes of managing, developing, and advancing Internet Drafts.
This assumes some familiarity with git. See the git basics for a primer on basic git concepts.
GitHub
GitHub is a platform that hosts Git repositories and provides a web interface for interacting with and managing repositories. Beyond basic Git functionality, GitHub provides the following features that are useful for Internet Draft document management:
- Code review: Prepare, review, and merge PRs.
- Issue tracking: A single, per-repository mechanism for collecting draft feedback, reporting issues, and organize tasks.
- Pull requests or PR: A request to take new changes from one branch and merge them into another branch. On GitHub, this is the primary way in which changes are contributed.
- Documentation: Wiki-style documentation pages that track miscellaneous information and content inappropriate for Internet Drafts yet still relevant to the work, such as pointers to software implementations, test vectors, or other testing tools.
- Content hosting: Web hosting for Internet Draft pages.
The following resources should help getting started with GitHub:
Mode Workflows
The following workflows assume your development machine is setup accordingly. Please see the instructions here for more details.
Document Management Mode
This mode of interaction uses GitHub primarily as a Git provider. Thus, it describes how to create document repositories, modify them, and prepare and upload submissions. For those who do not wish to use a command-line interface to modify documents, please check out the GitHub desktop application for assistance.
Document Repository Creation
Detailed steps for creating a repository using the i-d-template tool from Martin Thomson can be found here.
Document Modification
A common workflow for editing documents is roughly as follows:
- Fork the repository, if not already done, and clone it to your development machine.
$ git clone git@github.com:ietf-gitwg/ietf-gitwg.github.io.git
- Identify a branch in the forked repository for your work. This could be “master”, or a new branch. Depending on your use case, it may be easiest to work from “master”. However, for this example, we assume that changes work on change-specific branches. For example, if the specific change you intend to make is “add feature foo”, the branch name might be “add-foo-feature”. Or, if applying simple editorial changes, the branch might be named “edits”. (Note that branch names must be unique within a repository, so “edits” is only useful insofar as it is deleted when finished.)
$ git checkout -b edits
- Make changes on the document as needed for the change.
$ vim README.md
... fix typo ...
- Add the changes locally, commit them to the branch, and push to the remote repository.
$ git add README.md
$ git commit -m "Fix typo in README.md"
$ git push -u origin edits
In the above sequence of commands, we first stage the changes to README.md for commit via git add. We then commit them with the corresponding message “Fix typo in README.md”. If the commit message were not specified at the command line, git commit would open the default editor for this message to be specified. The message should describe what the change does. The last command pushes the commits on branch “edits” to the remote server “origin”. The “-u” flag makes it so that subsequent pushes to the same branch, on the same remote repository, only require you to run git push.
More details about the add, commit, push workflow can be found here.
- Open a Pull Request for merging the changes into “master”.
Document Submission
When an updated version of the document needs to be uploaded to the datatracker, we need to compile a version for submission. Details for this using the i-d-template toolchain are described here. For completeness, we summarize the manual approach here.
Assume we’re building a document entitled “draft-ietf-unicorn-protocol.md”. We begin by making the version for submission:
$ make submit
This will produce “draft-ietf-unicorn-protocol-00.xml” (among other files). You may then submit this XML file directly to the datatracker.
When complete, we “tag” this version, like so:
$ git tag -a draft-ietf-unicorn-protocol-00
$ git push origin draft-ietf-unicorn-protocol-00
This ensures that, the next time we run make submit, the version number increases from 00 to 01. (The i-d-template tool uses git tags to determine what version to produce next.)
Issue Tracking Mode
This mode of interaction assumes more familiarity with GitHub issues. There are plenty of helpful resources to get going, including, though not limited to:
An example of issues used for tracking purposes for the TLS Encrypted SNI document is shown below.
Issue Discussion Mode
This mode of interaction assumes familiarity with GitHub labels. Helpful resources to better understand and use them include:
Beyond using labels to help triage and discuss issues, this mode may also involve use of GitHub’s project boards. An example of the project board in use for the QUIC repository is shown below.
