| Internet-Draft | Pre-Event Practice Draft | April 2022 |
| Stark | Expires 4 October 2022 | [Page] |
Connections participants would like some simple instruction in creating IETF drafts. This draft tries to provide that.¶
This note is to be removed before publishing as an RFC.¶
Source for this draft and an issue tracker can be found at https://github.com/bhstark2/connections-practice-draft.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 4 October 2022.¶
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Connections participants would like some simple instruction in creating IETF drafts. This draft tries to provide that by providing important links and basic information. This draft doesn't actually use any normative language, but has left the boilerplate for that in the next section, for grins and giggles.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
People who want to be authors needs a GitHub account to contribute to a draft being written in GitHub. To set up a GH account, go to https://github.com/ and enter a preferred username, the email address you want to associate with the account (personal or work, depending on preferences and your corporate policies), and a password. GH will impose username uniqueness and password strength.¶
The https://github.com/ page defaults to "Sign Up". Click "Sign In" at the upper right to get the "Sign In" page if you already have an account.¶
This will set up a repository and draft template for automated IETF markdown -> xml and html generation.¶
Note: Only one person needs to do this, and not all authors of a draft.¶
Start from: https://github.com/martinthomson/i-d-template/blob/main/doc/TEMPLATE.md¶
Consider bookmarking this. All other steps flow from here.¶
You should see the rendered README.md below the list of files at this URL. If not, scroll down to it. Do step 1 (including clicking on the link), which says: Create a new repository using the template. Check "Include all branches", or you will need to enable GitHub Pages manually after step 2.¶
And then do step 2: Rename your draft and add a title.¶
You're now ready to edit your draft and add collaborators/authors.¶
You'll see there are a lot of Settings you can play with, depending on how people are behaving and other preferences. A couple of settings I like:¶
These rules assume the person is a Collaborator with Editor privilege. I provide the following 2 paragraphs as rules to my collaborators.¶
In the repository, click on the file you want to edit, and then click on the pencil icon in the upper right of the file. Do your edits. When done, scroll to the bottom of the page, select the checkbox that says "Create a new branch for this commit and start a pull request" (this is really important), and click on the "Propose Changes" button. If the button says "Commit Changes" instead of "Propose Changes", then you need to click the "Create a new branch for this commit and start a pull request" button first. On the next page that appears, click "Create pull request". If you think some description of your changes might help, feel free to enter something in the "Leave a comment" box (either for Propose Changes or the Pull Request).¶
If you want to work on the Pull Request (PR) over time or provide additional edits to your existing PR, you can do this at any time before the PR is merged. To do this, you simply edit files in your newly created branch. Select your branch from the pulldown menu (default branch in the pulldown is "Main") at the upper left of the repository Code page. The pulldown menu is located right under the <> Code tab heading.¶
There are many flavors of markdown. There is no single markdown "standard" (i.e., there are many markdown standards). Most have similar (but not identical) syntax rules.¶
The template uses kramdown-rfc: https://github.com/cabo/kramdown-rfc. There is another flavor of markdown that also has support for RFC metadata. But kramdown-rfc is well-supported for IETF drafts, works great, is easy to use and learn, and the template is already formatted for it.¶
See https://kramdown.gettalong.org/syntax.html#structural-elements. But the main thing you need to know is to put blank lines between paragraphs. There are 2 header styles supported. Pick one and be consistent.¶
See https://github.com/cabo/kramdown-rfc#the-yaml-header for the draft document metadata (draft title, authors, date, etc.).¶
See https://github.com/cabo/kramdown-rfc#references for formatting references. Referencing IETF RFCs and drafts is incredibly easy, thanks to the great tools that make magic happen behind the scenes.¶
This all happens like magic with every merged pull request, thanks to the automated workflows Martin has in that i-d-template repo we started from.¶
Use GitHub repository Settings to secure access to your draft. You can even make it private, if you don't want anyone to see it. Be careful doing that, though, because GH sets a max storage limit on private repos.¶
This document has no IANA actions.¶
Obviously, we have to thank Martin Thomson and Carsten Bormann for the amazing tools that make this all work.¶