! Anyone using the Travis configuration with versions of this prior to 2015-10-16 should delete any Github account tokens used. Travis logs might contain your token.

The contents of this repository can be used to get started with a new internet draft.

This all assumes that you have an account with GitHub and that you have your machine setup.

Make a new organization for your working group. This guide will use the name unicorn-wg for your working group.

See the more detailed guide.

Make a new repository. This guide will use the name name unicorn-protocol here.

When prompted, select the option to initialize the repository with a README.

Clone that repository:

$ git clone https://github.com/unicorn-wg/unicorn-protocol.git
$ cd unicorn-protocol

Create a git submodule that references this respository:

$ git submodule add https://github.com/martinthomson/i-d-template lib

Choose whether you want to use markdown, outline, or xml as your input form. If you already have a draft, then that decision is already made for you.

Make a draft file. The name of the file is important, make it match the name of your draft. You can take a copy of the example files if you are starting from scratch.

Edit the draft so that it has both a title and the correct name. These tools uses the -latest suffix in place of the usual number ('-00', or '-08'). The number is generated automatically when you use make submit.

In XML, you should have something like:

<rfc docName="draft-ietf-unicorn-protocol-latest"
     ... other attributes ...>
  <front>
    <title abbrev="Unicorns!!!">The Unicorn Protocol</title>

Markdown is similar:

docname: draft-ietf-unicorn-protocol-latest
title: The Unicorn Protocol

Now, run the setup commands:

$ make -f lib/setup.mk

This removes adds some files, updates README.md with the details of your draft, sets up a gh-pages branch for your editor's copy.

Check that everything looks OK, then push.

$ git push

You can maintain gh-pages manually by running the following command occasionally.

$ make ghpages

Or, you can setup an automatic commit hook using Travis or Circle CI.

This requires that you sign in with Travis or Circle.

First enable builds for the new repository: Travis, Circle. Travis might need to be refreshed before you can see your repository.

Then, you need to get yourself a new GitHub application token. The application token only needs the public_repo privilege. This will let it push updates to your gh-pages branch.

You can add environment variables using the Travis or Circle interface. Include a variable with the name GH_TOKEN and the value of your newly-created application token. On Travis, make sure to leave the value of "Display value in build log" disabled, or you will be making your token public.

WARNING: You might want to use a dummy account for application tokens to minimize the consequences of accidental leaks of your key.

Once you enable pushes, be very careful merging pull requests that alter .travis.yml, circle.yml or Makefile. Those files can cause the value of the token to be published for all to see. You don't want that to happen. Even though tokens can be revoked easily, discovering a leak might take some time. Only pushes to the main repository will be able to see the token, so don't worry about pull requests.

As a side benefit, Travis and Circle will now also check pull requests for errors, letting you know if things didn't work out so that you don't merge anything suspect.

Occasionally improvements and changes are made to the Makefile or the support files in this repository. Just change to the lib directory, pull down the changes, and commit:

$ git -C lib pull origin master
$ git commit -a
$ git push

On other clones, you will need to update when you do this:

$ git pull
$ git submodule update

See the submission guide.