This page is meant to help IETF contributors new to Git start using GitHub.
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 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:
The following resources should help getting started with GitHub:
The following workflows assume your development machine is setup accordingly. Please see the instructions here for more details.
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.
A common workflow for editing documents is roughly as follows:
$ git clone firstname.lastname@example.org:ietf-gitwg/ietf-gitwg.github.io.git
$ git checkout -b edits
$ vim README.md ... fix typo ...
$ 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
More details about the add, commit, push workflow can be found here.
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
01. (The i-d-template tool uses git tags to determine what version to produce next.)
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.
This mode of interaction assumes familiarity with GitHub labels. Helpful resources to better understand and use them include: