RPC Wiki

User Tools

Site Tools

Trace:
internet-draft-template-repo-instructions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

— internet-draft-template-repo-instructions [2025/10/29 09:43] (current)
jmahoney created
Line 1: Line 1:
 +====== Using GitHub: Martin Thomson's internet-draft-template repo ======
  
 +IETF community member [[https://datatracker.ietf.org/person/mt@lowentropy.net|Martin Thomson]] created a public template in GitHub that many IETFers use to start their GitHub repos for their Internet-Drafts.
 +
 +===== Prerequisites =====
 +
 +If you have not already done so, set up [[https://docs.github.com/en/pages/quickstart|GitHub Pages]].
 +
 +===== Startup =====
 +
 +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. 
 +
 +
 +===== Initial repo contents =====
 +
 +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 [[https://github.com/martinthomson/i-d-template/blob/main/doc/FEATURES.md|list of features]].
 +
 +====Branches, files, and directories====
 +
 +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 ====
 +
 +[[https://github.com/features/actions|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): [[https://github.com/martinthomson/i-d-template/blob/main/doc/SUBMITTING.md|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.
 +
 +===== Finishing setup =====
 +
 +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 [[https://github.com/martinthomson/i-d-template/blob/main/doc/TEMPLATE.md|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.
 +
 +==== Troubleshooting ====
 +
 +If **Perform Initial Repository Setup** fails, it is most likely due to [[https://github.com/cabo/kramdown-rfc/wiki/Pitfalls#trailing-whitespace|trailing whitespace]] that was added to the I-D markdown file. Remove any trailing whitespace and commit your changes. 
 +
 +==== Updated repo contents ====
 +
 +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 [[https://git-scm.com/docs/gitignore|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''.
 +
 +=== makefile ===
 +
 +The makefile (and supporting files) lets you perform the actions listed above and more from the command line (see [[https://github.com/martinthomson/i-d-template/blob/main/doc/SETUP.md|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. [[https://pages.github.com/|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 [[https://datatracker.ietf.org/api/submit|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 [[https://www.ietf.org/tools/idnits|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 [[https://github.com/martinthomson/i-d-template/blob/main/doc/UPDATE.md|instructions for keeping these files up to date]].
 +    * ''make update'' - for dealing with surprising errors.
 +
 +The make features are documented at [[https://github.com/martinthomson/i-d-template/blob/main/doc/FEATURES.md|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 [[https://github.com/martinthomson/i-d-template/blob/main/doc/TOOLS.md|guidance on extending your local toolset]]. 
 +
 +===== Updating the YAML header =====
 +
 +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
 +
 +==== "About This Document" section ====
 +
 +The [[https://github.com/cabo/kramdown-rfc/wiki/Syntax2#venue|fields in the venue block]] in the md file:
 +<code>
 +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"
 +</code>
 +
 +Are used to create the following output, which can be seen in the **gh-pages** branch:
 +<code>
 +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.
 +</code>
 +
 +===== Getting publishing to work =====
 +
 +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 [[https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site|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
 +
 +
 +===== Adding the real doc =====
 +
 +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) [[https://github.com/cabo/kramdown-rfc/wiki/Syntax2|listed here]]
 +
 +For RFCXML
 +  * docName in the <rfc> element needs to be of the form, //filename//-latest and match //filename//.xml.
internet-draft-template-repo-instructions.txt · Last modified: 2025/10/29 09:43 by jmahoney

Page Tools

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki