Merge with upstream.

Author: wolfmcnally

.circleci/config.yml

@@ -13,7 +13,7 @@ jobs:
     steps:
       - checkout
       - setup_remote_docker:
-          version: 20.10.6
+          version: default
 
       - run:
           name: "Build Docker Image"

.github/workflows/docker.yml

@@ -23,7 +23,7 @@ jobs:
 
     steps:
     - name: "Checkout"
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: "Configure"
       id: config
@@ -57,28 +57,28 @@ jobs:
         echo "math_tags=$math_tags" >>"$GITHUB_OUTPUT"
 
     - name: "Setup Docker Buildx"
-      uses: docker/setup-buildx-action@v2
+      uses: docker/setup-buildx-action@v3
       with:
         driver-opts: ${{ steps.config.outputs.driver_opts }}
 
     - name: "Login to GitHub Container Registry"
       if: ${{ steps.config.outputs.label != 'test' }}
-      uses: docker/login-action@v2
+      uses: docker/login-action@v3
       with:
         registry: ghcr.io
         username: ${{ secrets.GHCR_USERNAME }}
         password: ${{ secrets.GHCR_PASSWORD }}
 
     - name: "Build and Publish GitHub Actions Image"
-      uses: docker/build-push-action@v3
+      uses: docker/build-push-action@v6
       with:
         context: ./docker/action
         file: ./docker/action/Dockerfile
         push: true
         tags: ${{ steps.config.outputs.action_tags }}
 
     - name: "Build and Publish CircleCI Image"
-      uses: docker/build-push-action@v3
+      uses: docker/build-push-action@v6
       with:
         context: ./docker/circleci
         file: ./docker/circleci/Dockerfile
@@ -89,7 +89,7 @@ jobs:
         tags: ${{ steps.config.outputs.circle_tags }}
 
     - name: "Build and Publish Math Image"
-      uses: docker/build-push-action@v3
+      uses: docker/build-push-action@v6
       with:
         context: ./docker/math
         file: ./docker/math/Dockerfile

.github/workflows/template.yml

@@ -20,7 +20,7 @@ jobs:
 
     steps:
     - name: "Checkout"
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: "Verify Gemfile and requirements.txt consistency"
       run: |

Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
 gem 'kramdown-rfc'
-gem 'net-http-persistent'

config.mk

@@ -27,6 +27,12 @@ kramdown-rfc ?= kramdown-rfc
 export KRAMDOWN_NO_TARGETS := true
 export KRAMDOWN_PERSISTENT := true
 
+# Use an emoji for the favicon
+FAVICON_EMOJI ?=
+ifneq (,$(FAVICON_EMOJI))
+FAVICON ?= <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>$(FAVICON_EMOJI)</text></svg>">
+endif
+
 #  mmark (https://github.com/mmarkdown/mmark)
 mmark ?= mmark
 
@@ -39,7 +45,7 @@ oxtradoc ?= oxtradoc.in
 xsltproc ?= xsltproc
 
 # For sanity checkout your draft:
-#   https://www.ietf.org/tools/idnits
+#   https://github.com/ietf-tools/idnits
 idnits ?= idnits
 
 # For diff:
@@ -89,6 +95,15 @@ else
 ifeq (,$(KRAMDOWN_REFCACHEDIR))
 ifeq (true,$(CI))
 XML2RFC_REFCACHEDIR := $(realpath .)/.refcache
+# In CI, only cache drafts for 5 minutes to pick up on recent updates.
+export KRAMDOWN_REFCACHETTL := 300
+else
+# When running locally, cache drafts for a week.
+export KRAMDOWN_REFCACHETTL_RFC := 23673600
+# Cache IANA and DOI for 3 months since they change rarely.
+export KRAMDOWN_REFCACHETTL := 604800
+# Cache RFCs for 9 months since they are immutable.
+export KRAMDOWN_REFCACHETTL_DOI_IANA := 7776000
 endif
 XML2RFC_REFCACHEDIR ?= $(HOME)/.cache/xml2rfc
 KRAMDOWN_REFCACHEDIR := $(XML2RFC_REFCACHEDIR)

deps.mk

@@ -104,6 +104,21 @@
 
 .PHONY: deps clean-deps update-deps
 
+# Make really doesn't handle spaces in filenames well.
+# Using $(realpath) exposes make to spaces in directory names above this one.
+# Though we might prefer to use $(realpath), this function operates a fallback
+# so that the full path is not used if there are spaces in directory names.
+ifeq ($(words $(realpath $(LIBDIR))),1)
+safe-realpath = $(realpath $(1))
+relative-paths := false
+else
+ifneq (,$(DISABLE_SPACES_WARNING))
+$(warning Your $$LIBDIR ($(LIBDIR)) contains spaces; some things might break.)
+endif
+safe-realpath = $(1)
+relative-paths := true
+endif
+
 ifeq (true,$(DISABLE_CACHE))
 no-cache := --no-cache
 no-cache-dir := --no-cache-dir
@@ -114,10 +129,10 @@ endif
 
 ifeq (true,$(CI))
 # Override VENVDIR so we can use caching in CI.
-VENVDIR = $(realpath .)/.venv
+VENVDIR = $(call safe-realpath,.)/.venv
 endif
 
-VENVDIR ?= $(realpath $(LIBDIR))/.venv
+VENVDIR ?= $(call safe-realpath,$(LIBDIR))/.venv
 REQUIREMENTS_TXT := $(wildcard requirements.txt)
 
 ifneq (,$(strip $(REQUIREMENTS_TXT)))
@@ -137,7 +152,7 @@ ifeq (true,$(CI))
 # Under CI, install from the local requirements.txt, but install globally (no venv).
 pip ?= pip3
 $(LOCAL_VENV):
-	$(pip) install $(no-cache-dir) $(foreach path,$(REQUIREMENTS_TXT),-r $(path))
+	"$(pip)" install --no-user $(no-cache-dir) $(foreach path,$(REQUIREMENTS_TXT),-r $(path))
 	@touch $@
 
 # No clean-deps target in CI..
@@ -162,8 +177,8 @@ endif
 clean-deps:: clean-venv
 endif # CI
 update-deps::
-	$(pip) install $(no-cache-dir) --upgrade --upgrade-strategy eager \
-	  $(foreach path,$(REQUIREMENTS_TXT),-r $(path))
+	"$(pip)" install --no-user $(no-cache-dir) --upgrade --upgrade-strategy eager \
+	  $(foreach path,$(REQUIREMENTS_TXT),-r "$(path)")
 endif # -e requirements.txt
 
 # Variable defaults for CI
@@ -183,42 +198,55 @@ BUNDLE_IGNORE_MESSAGES := true
 export BUNDLE_IGNORE_MESSAGES
 ifeq (true,$(CI))
 # Override BUNDLE_PATH so we can use caching in CI.
-BUNDLE_PATH := $(realpath .)/.gems
+BUNDLE_PATH := $(call safe-realpath,.)/.gems
 BUNDLE_DISABLE_VERSION_CHECK := true
 export BUNDLE_DISABLE_VERSION_CHECK
 endif
-export BUNDLE_PATH ?= $(realpath $(LIBDIR))/.gems
+BUNDLE_PATH ?= $(call safe-realpath,$(LIBDIR))/.gems
 # Install binaries to somewhere sensible instead of .../ruby/$v/bin where $v
 # doesn't even match the current ruby version.
-export BUNDLE_BIN := $(BUNDLE_PATH)/bin
+BUNDLE_BIN := $(BUNDLE_PATH)/bin
 export PATH := $(BUNDLE_BIN):$(PATH)
+ifeq (true,$(relative-paths))
+# This means that BUNDLE_PATH is relative, which bundler will interpret
+# as being relative to the Gemfile, not the current directory, so tweak
+# the two path settings for bundler.  After setting $PATH.
+# Thankfully, we don't install from $(LIBDIR)/Gemfile in CI, which
+# would mean that this would need to be "../.gems" there.
+$(warning Using a relative path for bundler)
+bundle-path-override-lib := BUNDLE_PATH=$(LIBDIR)/.gems BUNDLE_BIN=$(LIBDIR)/.gems/bin
+bundle-path-override := BUNDLE_PATH=.gems BUNDLE_BIN=.gems/bin
+endif
+export BUNDLE_PATH
+export BUNDLE_BIN
+
 
 ifneq (,$(wildcard Gemfile))
 # A local Gemfile exists.
 DEPS_FILES += Gemfile.lock
 Gemfile.lock: Gemfile
-	bundle install $(no-cache) --gemfile=$(realpath $<)
+	$(bundle-path-override-lib) bundle install $(no-cache) --gemfile="$(call safe-realpath,$<)"
 	@touch $@
 
 update-deps:: Gemfile
-	bundle update $(bundle-update-all) --gemfile=$(realpath $<)
+	$(bundle-path-override-lib) bundle update $(bundle-update-all) --gemfile="$(call safe-realpath,$<)"
 
 clean-deps::
-	-rm -rf $(BUNDLE_PATH)
+	-rm -rf "$(BUNDLE_PATH)"
 endif # Gemfile
 
 ifneq (true,$(CI))
 # Install kramdown-rfc.
 DEPS_FILES += $(LIBDIR)/Gemfile.lock
 $(LIBDIR)/Gemfile.lock: $(LIBDIR)/Gemfile
-	bundle install $(no-cache) --gemfile=$(realpath $<)
+	$(bundle-path-override) bundle install $(no-cache) --gemfile="$(call safe-realpath,$<)"
 	@touch $@
 
 update-deps:: $(LIBDIR)/Gemfile
-	bundle update $(bundle-update-all) --gemfile=$(realpath $<)
+	$(bundle-path-override) bundle update $(bundle-update-all) --gemfile="$(call safe-realpath,$<)"
 
 clean-deps::
-	-rm -rf $(BUNDLE_PATH)
+	-rm -rf "$(BUNDLE_PATH)"
 endif # !CI
 endif # !NO_RUBY
 
@@ -232,8 +260,8 @@ NO_NODEJS := true
 endif
 
 ifneq (true,$(NO_NODEJS))
-ifneq (,$(wildcard package.json))
 export PATH := $(abspath node_modules/.bin):$(PATH)
+ifneq (,$(wildcard package.json))
 DEPS_FILES += package-lock.json
 package-lock.json: package.json
 	npm install

doc/FEATURES.md

@@ -7,7 +7,12 @@ $ make
 Turn internet-draft source into text and HTML.  This supports XML files using
 [xml2rfc](https://xml2rfc.tools.ietf.org/), markdown files using either
 [kramdown-rfc](https://github.com/cabo/kramdown-rfc) or
-[mmark](https://github.com/miekg/mmark)
+[mmark](https://github.com/miekg/mmark).
+
+Multiple files can be managed in the same repository.  This only requires the
+addition of the source files for each draft, though you might choose to
+[update](https://github.com/martinthomson/i-d-template/blob/main/doc/UPDATE.md#automatically-generated-files)
+some files.
 
 ```sh
 $ make diff
@@ -60,6 +65,11 @@ $ make issues
 
 Download a copy of GitHub issues and pull requests.
 
+If there are surprising errors, this may help:
+```sh
+$ make clean
+```
+
 
 ## Setup a Repository
 

doc/SETUP.md

@@ -19,7 +19,20 @@ These tools work well natively on Linux and Mac.
 
 Windows users should use [the Windows Subsystem for
 Linux](https://docs.microsoft.com/en-us/windows/wsl/install) with a Linux
-distribution like Ubuntu (`wsl --install -d Ubuntu`) to get `make`.
+distribution like Ubuntu (`wsl --install -d Ubuntu` from an administrator
+prompt).
+
+From within Ubuntu, you can install the dependencies for this repository:
+
+```sh
+sudo apt-get install -y git make python3-pip python3-venv
+```
+
+You can also add recommended packages, as follows:
+
+```sh
+sudo apt-get install -y ruby-bundler npm libxml2-utils
+```
 
 It is also possible to use [cygwin](https://cygwin.org/) or an
 [MSYS2](https://www.msys2.org/)-based system (like

doc/SUBMITTING.md

@@ -68,6 +68,36 @@ This will attribute the submission to the first author listed in the draft, no
 matter who generated the release, just like with a lightweight tag.
 
 
+## Picking an Email
+
+The IETF datatracker is quite picky about the email that is associated with a
+submission.  To work around that, there are several ways email addresses are
+chosen for a submission.
+
+1. An email address can be set when manually running the GitHub action.
+   This isn't a common way of requesting submission, but you might manually run
+   the action if a build fails.
+
+3. Setting a variable called `UPLOAD_EMAIL` in your Makefile.  Make sure to
+   export the value:
+
+```make
+export UPLOAD_EMAIL ?= [email protected]
+```
+
+3. The email address you used to create the tag (annotated tags only).
+   This will come from your git configuration.
+
+4. Your GitHub account email address.
+
+5. The email address of the first author in the draft.
+
+You can tell datatracker about your email address(es)
+[here](https://datatracker.ietf.org/accounts/profile/).  You might need to
+ensure that the first email the above process finds is the primary address
+known to the datatracker.
+
+
 ## If the Build Fails
 
 Sometimes the build will fail.  Some errors can be worked around by retrying the

doc/TEMPLATE.md

@@ -10,13 +10,9 @@ simple process.
 1. [Create a new repository using the
    template](https://github.com/martinthomson/internet-draft-template/generate).
    Check "Include all branches", or you will need to enable GitHub Pages
-   manually after step 2.
-   
-2. Allow GitHub Workflows to make changes to the repository.  Click the gear icon
-   to open the settings for your repo, then select Actions > General in the list
-   on the left.  Under "Workflow permissions", select "Read and write permissions".
+   manually.
 
-3. Rename your I-D and add a title.  The newly created repository will contain
+2. Rename your I-D and add a title.  The newly created repository will contain
    a link to a page where you can do this using the GitHub editor.  Setup will
    automatically run.  Setup should be done in less than a minute.