Using GitHub: Martin Thomson's internet-draft-template repo

IETF community member Martin Thomson created a public template in GitHub that many IETFers use to start their GitHub repos for their Internet-Drafts.

If you have not already done so, set up GitHub Pages.

To create a new repo using this template:

• Go to https://github.com/martinthomson/internet-draft-template.
• Click the green Use this template button and select Create a new repository. The Create a new repository page appears.
• Check the Include all branches box.
• Provide a name for the repo.
• Select whether the repo should be public or private. Not all features of the template are available to a private repository, though, and some workflows may not work.
• Click the green Create repository button. Your new repo appears.

When the repo is created from the template, it is not empty. It contains two branches, some stub files, which will need review and some editing, and some GitHub actions, which are scripts that can publish output and check for errors.

See also the list of features.

The new repo has two branches:

• main - editing work is expected to take place on this branch and PRs should be branched off this. Initial contents:
  • .github/workflows/ - a directory that stores GitHub Action files:
    • LICENSE.md
    • archive.yml
    • ghpages.yml
    • publish.yml
    • setup.yml
    • update.yml
  • draft-todo-yourname-protocol.md - a barebones I-D in kramdown-rfc.
  • README.md
• gh-pages - a branch that will contain document output, but initially just has:
  • .gitignore
  • archive.json - an empty file
  • draft-todo-yourname-protocol.html - an HTML file of the barebones I-D
  • draft-todo-yourname-protocol.txt - a text file of the barebones I-D
  • index.html - an HTML page for your repo that provides links to your I-D's datatracker page and the latest diff file.

GitHub Actions provide automated continuous integration that can:

• Archive Issues and Pull Requests (archive.yml): Automatically save a copy of GitHub issues and pull requests to the repository for offline access. This includes a simple HTML viewer.
• Perform Initial Repository Setup (setup.yml): This performs some initial setup steps and then deletes itself.
• Publish New Draft Version (publish.yml): Automatically submit tagged versions of drafts to the IETF datatracker.
• Update Editor's Copy (ghpages.yml): Checks commits and pull requests for errors. This action runs for every PR and commit. It can maintain a readable copy for display on GitHub Pages (for public repos only; no output is posted to github.io if the repo is private).
• Update Generated Files (update.yml): a manually run action that can update the README, CONTRIBUTING, CODEOWNERS, and makefile files if the document's title, filename, or authors have changed.

These actions can be found on the Actions tab, and their code (i.e., the YAML files) can be found in the directory .github/workflows on the main branch.

When you click the Actions tab, you will see that three actions (Perform Initial Repository Setup, Update Editor's Copy and pages-build-deployment) have been performed.

In the repo that you have created:

• Rename draft-todo-yourname-protocol.md by following the link in the README.
  • Follow the instructions in the comments of the file:
    • Add a title to your draft.
    • Commit your changes.
    • You will receive a 404 message because the repo is not fully set up.
    • Click the green Return to repository overview button.
• Click the Actions tab. You should see that Update Editor's Copy, pages-build-deployment, and Perform Initial Repository Setup ran again.
  • Update Editor's Copy may fail because of the path issue.
  • Perform Initial Repository Setup succeeded. Note that the action is no longer listed on the left-hand side: it deletes itself upon success.

The template documentation notes that:

It is not possible to update workflows (the files GitHub Actions use) from an action unless you use custom personal access tokens. Rather than complicate the setup process by requiring a token, this template includes all the necessary workflow files from the beginning, plus a special setup workflow. Before the repository is properly setup, the other workflows will fail immediately (and safely). The setup workflow removes itself once it is successful.

If Perform Initial Repository Setup fails, it is most likely due to trailing whitespace that was added to the I-D markdown file. Remove any trailing whitespace and commit your changes.

Once you have successfully set up the repo, the contents of the main branch will be updated with the following files:

• .editorconfig - see https://editorconfig.org/ for more info
• .gitignore - a file containing a list of things that Git and GitHub will ignore
• CONTRIBUTING.md - a file that provides a very high-level IETF Note Well
• LICENSE.md - a file that points to the CONTRIBUTING.md file
• Makefile - see details below
• filename.md - the setup modifies the following YAML fields after your edit:
  • setup deletes the comments that contained the instructions for editing the file.
  • If you did not provide any area or WG info, the fields in the YAML header will be commented out (with #, but the file viewer in GitHub will interpret these as headings, which will direct your attention to them).
  • docname: updated to use the name you gave the file.
  • email: updated to use the email you have on file with GitHub.
  • github: updated to use your repo info.
  • latest: now contains a URL to your repo's github.io page that will display I-D output once it is created.
• README.md - the instructions on setting up the repo have been replaced with a discussion of the I-D with links to the output (the datatracker and diff links won't work yet), the CONTRIBUTING file, and brief introduction to make.

The makefile (and supporting files) lets you perform the actions listed above and more from the command line (see Installation and Setup for other things you need to do to get command line tools to work):

• make - runs xml2rfc to create HTML and text files from markdown files (either kramdown or mmark).
• make diff - creates an rfcdiff between your current text file and the last file that you submitted to datatracker.
• make gh-pages - Update the gh-pages branch with the latest edits. GitHub pages make your changes available on the web. There is also a GitHub Action to do this.
• make upload - Upload tagged changes to the IETF datatracker using the API. To tag, use a new version of an I-D draftstring, e.g., git tag -a draft-ietf-unicorn-protocol-02
• makefile options for checking documents:
  • make lint - Check for common formatting errors like trailing whitespace
  • make fix-lint - Fix found issues
  • make idnits - Checks for nits using idnits
  • make issues - Download a copy of GitHub issues and pull requests.
    • For offline access. There is also a GitHub Action that does this.
• make update - updates the repo code and any dependencies. See instructions for keeping these files up to date.
• make update - for dealing with surprising errors.

The make features are documented at What This Project Can Do.

Note that, while running these commands from the command line is optional, there are some tools available at the CLI that are not available with GitHub Actions. It may also be easier to extend tooling on the CLI. See the guidance on extending your local toolset.

Right now, there's just a barebones kramdown-rfc file. Updating the fields that need attention is a good way to test the repo.

After updating the YAML header and merging the PR successfully into main, the following updates are made to the gh-pages branch:

• a directory named after the PR branch has been added. It contains the text and HTML outputs of the file.
• index.html - a new file that points the text and HTML outputs.
• filename.txt - HTML output
• filename.html - HTML output

The fields in the venue block in the md file:

venue:
  group: flowers
  type: Working Group
  mail: flowers@example.com
  arch: "https://mailarchive.ietf.org/arch/browse/flowers"
  github: "ajeanmahoney/zinnia"
  latest: "https://ajeanmahoney.github.io/zinnia/draft-mahoney-zinnia.html"

Are used to create the following output, which can be seen in the gh-pages branch:

About This Document

   This note is to be removed before publishing as an RFC.

   The latest revision of this draft can be found at
   https://ajeanmahoney.github.io/zinnia/draft-mahoney-zinnia.html.
   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-mahoney-zinnia/.

   Discussion of this document takes place on the flowers Working Group
   mailing list (mailto:flowers@example.com), which is archived at
   https://mailarchive.ietf.org/arch/browse/flowers.

   Source for this draft and an issue tracker can be found at
   https://github.com/ajeanmahoney/zinnia.

In order to make the output available, the repo must either be public or you must have a paid subscription to GitHub.

(The following is not documented in Thomson's docs because it's set up automatically if you create a public repo, but is documented here)

If you have changed a private repo to public and would like to have the output publicly available, then under Settings:

• Select Pages under Code and Automation on the left-hand side.
• Under the Build and deployment section:
  • Ensure Deploy from branch is selected.
  • Select gh-pages and /(root) from the drop-downs.
• Click Save. This adds the pages-build-deployment action to the Actions tab.
• You should now be able to access the output at username.github.io/repo/filename.html

The next step is to get a real I-D into the repo.

For kramdown- rfc, the following YAML fields are required:

• by the repo:
  • docname: Needs to be of the form, filename-latest (e.g., draft-mahoney-zinnia-latest) with no file extension nor version number. If filename of filename-latest does not match filename.md, then checks will fail.
• by kramdown-rfc:
  • (not all are necessarily required) listed here

For RFCXML

• docName in the <rfc> element needs to be of the form, filename-latest and match filename.xml.