PRE-EVENT B. Stark Internet-Draft None (Retired) Intended status: Informational 2 April 2022 Expires: 4 October 2022 Connections Pre-Event Practice IETF Draft draft-stark-connections-pre-event-draft-latest Abstract Connections participants would like some simple instruction in creating IETF drafts. This draft tries to provide that. Discussion Venues 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. Status of This Memo 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 Notice 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. Table of Contents 1. Introduction 2. Conventions and Definitions 3. Connections pre-event-preparation 3.1. Signing up for a GitHub (GH) account 3.2. Signing in to GH 4. Topics we will cover 4.1. Setting up the GitHub repository 4.2. Adding collaborators / authors 4.3. Other Settings 4.4. Rules I've used with great success 4.5. Kramdown-rfc markdown 4.6. Basic markdown syntax 4.7. IETF metadata 4.8. Generating the xml, txt, and html 5. Security Considerations 6. IANA Considerations 7. Normative References Acknowledgments Author's Address 1. Introduction 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. 2. Conventions and Definitions 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. 3. Connections pre-event-preparation 3.1. Signing up for a GitHub (GH) account Everyone needs a GitHub account to contribute to a draft being written in GitHub. To set up a GH account, go to https://github.com/ (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. 3.2. Signing in to GH The https://github.com/ (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. 4. Topics we will cover 4.1. Setting up the GitHub repository 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 (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. 4.2. Adding collaborators / authors Repository default settings allow anyone logged in to GH to create a fork of the repository, make changes in their fork, and then create a Pull Request (PR). But that's not a great experience for novice collaborators. Get the GH account names of your collaborators and explicitly add them to the repository Collaborator list (there should be a little gear symbol with "Settings" next to it in the top menu for your repo -- Collaborators is the first option listed in the left menu of Settings). If you trust your collaborators to follow your rules, you should give them Editor privilege. 4.3. Other Settings 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: * in General (towards the bottom): Automatically delete head branches * in Branches, branch protection rules for Main branch: Require a pull request before merging 4.4. Rules I've used with great success 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. 4.5. Kramdown-rfc markdown 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 (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. 4.6. Basic markdown syntax See https://kramdown.gettalong.org/syntax.html#structural-elements (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. 4.7. IETF metadata See https://github.com/cabo/kramdown-rfc#the-yaml-header (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 (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. 4.8. Generating the xml, txt, and html 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. 5. Security Considerations 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. 6. IANA Considerations This document has no IANA actions. 7. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Acknowledgments Obviously, we have to thank Martin Thomson and Carsten Bormann for the amazing tools that make this all work. Author's Address Barbara Stark None (Retired) Email: bhstark2@users.noreply.github.com