Merge pull request theupdateframework#148 from joshuagl/joshuagl/gha-ci

GitHub Actions workflow to publish specification to GitHub Pages

.github/workflows/draft.yml

@@ -0,0 +1,53 @@
+name: Update draft specification
+on:
+  workflow_dispatch:
+  push:
+    branches: draft
+
+jobs:
+  build-draft:
+    name: Make draft spec release
+    runs-on: ubuntu-latest
+    steps:
+    - name: Set up Python
+      uses: actions/setup-python@3105fb18c05ddd93efea5f9e0bef7a03a6e9e7df
+      with:
+        python-version: 3.x
+
+    - name: Find pip cache dir
+      id: pip-cache
+      run: echo "::set-output name=dir::$(pip cache dir)"
+
+    - name: pip cache
+      uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6
+      with:
+        # Use the os dependent pip cache directory found above
+        path: ${{ steps.pip-cache.outputs.dir }}
+        # A match with 'restore-keys' is used as fallback
+        key: ${{ runner.os }}-pip-
+
+    - name: Clone
+      uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+
+    - name: Build specification
+      run: |
+        python -m pip install bikeshed
+        mkdir build && cd build
+        make -f ../Makefile draft
+
+    - name: Switch branch
+      uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+      with:
+        ref: gh-pages
+        clean: false
+
+    - name: Push generated specification
+      run: |
+        git config user.name "TUF Specification Automation"
+        git config user.email [email protected]
+        rm -fr draft
+        mv build/* .
+        rmdir build
+        git add .
+        git commit -m "Publish latest draft specification"
+        git push

.github/workflows/pr.yml

@@ -0,0 +1,20 @@
+name: CI
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  main:
+    name: Check date and version are updated
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0 # we want all refs for the --is-ancestor check
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - name: Check date and version
+        run: python check_release.py

.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Release specification
+on:
+  workflow_dispatch:
+  push:
+    branches: master
+
+jobs:
+  make-release:
+    name: Make and publish spec release
+    runs-on: ubuntu-latest
+    steps:
+    - name: Set up Python
+      uses: actions/setup-python@3105fb18c05ddd93efea5f9e0bef7a03a6e9e7df
+      with:
+        python-version: 3.x
+
+    - name: Find pip cache dir
+      id: pip-cache
+      run: echo "::set-output name=dir::$(pip cache dir)"
+
+    - name: pip cache
+      uses: actions/cache@26968a09c0ea4f3e233fdddbafd1166051a095f6
+      with:
+        # Use the os dependent pip cache directory found above
+        path: ${{ steps.pip-cache.outputs.dir }}
+        # A match with 'key' counts as cache hit
+        key: ${{ runner.os }}-pip-
+
+    - name: Clone main
+      uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+      with:
+        fetch-depth: 0
+
+    - name: Get previous version
+      id: prevver
+      run: |
+        prev_version=`git tag | sort -V -r | head -n 1 | cut -c 2-`
+        echo "::set-output name=prev_version::$(echo -n $prev_version)"
+
+    - name: Get version
+      id: getver
+      run: |
+        spec_version=`grep -oP 'VERSION \K(\d+\.\d+\.\d+)' tuf-spec.md`
+        echo "::set-output name=spec_version::$(echo -n $spec_version)"
+
+    - name: Make release
+      if: steps.getver.outputs.spec_version != steps.prevver.outputs.prev_version
+      uses: actions/create-release@0cb9c9b65d5d1901c1f53e5e66eaf4afd303e70e
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: v${{ steps.getver.outputs.spec_version }}
+        release_name: v${{ steps.getver.outputs.spec_version }}
+        body: Specification release v${{ steps.getver.outputs.spec_version }}
+
+    - name: Build specification
+      if: steps.getver.outputs.spec_version != steps.prevver.outputs.prev_version
+      run: |
+        python -m pip install bikeshed
+        mkdir build && cd build
+        make -f ../Makefile release
+
+    - name: Switch branch
+      if: steps.getver.outputs.spec_version != steps.prevver.outputs.prev_version
+      uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+      with:
+        ref: gh-pages
+        clean: false
+
+    - name: Push generated specification
+      if: steps.getver.outputs.spec_version != steps.prevver.outputs.prev_version
+      env:
+        SPEC_VERSION: v${{ steps.getver.outputs.spec_version }}
+      run: |
+        git config user.name "TUF Specification Automation"
+        git config user.email [email protected]
+        rm -fr latest
+        mv build/* .
+        rmdir build
+        make index
+        git add .
+        git commit -m "Publish latest specification $SPEC_VERSION"
+        git push

Makefile

@@ -1,5 +1,23 @@
 SHELL=/bin/bash -o pipefail
-.PHONY: local
+SPEC_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
+.PHONY: spec
 
-local: tuf-spec.md
-	bikeshed spec tuf-spec.md tuf-spec.html
+spec: $(SPEC_DIR)/tuf-spec.md
+	bikeshed spec $(SPEC_DIR)/tuf-spec.md tuf-spec.html
+
+latest: spec
+	mkdir -p latest
+	cp tuf-spec.html latest/index.html
+
+draft: spec
+	mkdir -p draft
+	cp tuf-spec.html draft/index.html
+
+versioned: spec
+	mkdir -p $(shell python3 $(SPEC_DIR)/get_version.py $(SPEC_DIR)/tuf-spec.md)
+	cp tuf-spec.html $(shell python3 $(SPEC_DIR)/get_version.py $(SPEC_DIR)/tuf-spec.md)/index.html
+
+index:
+	python3 $(SPEC_DIR)/build_index.py
+
+release: spec latest versioned

build_index.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+
+"""
+<Program Name>
+  build_index.py
+
+<Author>
+  Joshua Lock <[email protected]>
+
+<Started>
+  Feb 1, 2021
+
+<Copyright>
+  See LICENSE-MIT for licensing information.
+
+<Purpose>
+  Quick and dirty script to generate an index of published specification
+  versions.
+
+  Style cribbed from the bikeshed W3C theme we are using in our bikeshed
+  generated specification documents.
+"""
+
+import os
+import sys
+
+from subprocess import run
+
+html_header = """<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+  <title>The Update Framework Specification</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+  <style data-fill-with="stylesheet">
+  body {
+    counter-reset: example figure issue;
+
+    /* Layout */
+    max-width: 50em;			  /* limit line length to 50em for readability   */
+    margin: 0 auto;				/* center text within page                    */
+    padding: 1.6em 1.5em 2em 50px; /* assume 16px font size for downlevel clients */
+    padding: 1.6em 1.5em 2em calc(26px + 1.5em); /* leave space for status flag    */
+
+    /* Typography */
+    line-height: 1.5;
+    font-family: sans-serif;
+    widows: 2;
+    orphans: 2;
+    word-wrap: break-word;
+    overflow-wrap: break-word;
+    hyphens: auto;
+
+    color: black;
+    color: var(--text);
+    background: white top left fixed no-repeat;
+    background: var(--bg) top left fixed no-repeat;
+    background-size: 25px auto;
+  }
+  div.head { margin-bottom: 1em; }
+  div.head h1 {
+      font-weight: bold;
+      margin: 0 0 .1em;
+      font-size: 220%;
+  }
+
+  p {
+      margin: 1em 0;
+  }
+
+  dd > p:first-child,
+  li > p:first-child {
+      margin-top: 0;
+  }
+
+  ul, ol {
+      margin-left: 0;
+      padding-left: 2em;
+  }
+
+  li {
+      margin: 0.25em 0 0.5em;
+      padding: 0;
+  }
+
+  a {
+      color: #034575;
+      color: var(--a-normal-text);
+      text-decoration: none;
+      border-bottom: 1px solid #707070;
+      border-bottom: 1px solid var(--a-normal-underline);
+      /* Need a bit of extending for it to look okay */
+      padding: 0 1px 0;
+      margin: 0 -1px 0;
+  }
+  a:visited {
+      color: #034575;
+      color: var(--a-visited-text);
+      border-bottom-color: #bbb;
+      border-bottom-color: var(--a-visited-underline);
+  }
+
+  a:focus,
+  a:hover {
+      background: #f8f8f8;
+      background: rgba(75%, 75%, 75%, .25);
+      background: var(--a-hover-bg);
+      border-bottom-width: 3px;
+      margin-bottom: -2px;
+  }
+  a:active {
+      color: #c00;
+      color: var(--a-active-text);
+      border-color: #c00;
+      border-color: var(--a-active-underline);
+  }
+
+  h1, h2, h3, h4, h5, h6, dt {
+      page-break-after: avoid;
+      page-break-inside: avoid;
+      font: 100% sans-serif;   /* Reset all font styling to clear out UA styles */
+      font-family: inherit;	/* Inherit the font family. */
+      line-height: 1.2;		/* Keep wrapped headings compact */
+      hyphens: manual;		/* Hyphenated headings look weird */
+  }
+  h2, h3, h4, h5, h6 {
+      margin-top: 3rem;
+  }
+  h1, h2, h3 {
+      color: #005A9C;
+      color: var(--heading-text);
+  }
+  h1 { font-size: 170%; }
+  h2 { font-size: 140%; }
+
+  :root {
+    color-scheme: light dark;
+
+    --text: black;
+    --bg: white;
+
+    --heading-text: #005a9c;
+
+    --a-normal-text: #034575;
+    --a-normal-underline: #707070;
+    --a-visited-text: var(--a-normal-text);
+    --a-visited-underline: #bbb;
+    --a-hover-bg: rgba(75%, 75%, 75%, .25);
+    --a-active-text: #c00;
+    --a-active-underline: #c00;
+  }
+  </style>
+</head>
+<body class="h-entry">
+<div class="head">
+  <h1 id="title" class="p-name no-ref">The Update Framework Specification</h1>
+</div>
+<div>
+<ul>
+"""
+
+html_footer = """</ul>
+</body>
+</html>
+"""
+
+def build_index():
+    html = html_header
+
+    html_locations = ['latest', 'draft']
+    dir_contents = sorted(os.listdir('.'), reverse=True)
+    for path in dir_contents:
+        if path.startswith('v'):
+            if not os.path.exists(f'{path}/index.html'):
+                continue
+            html_locations.append(path)
+
+    for loc in html_locations:
+        link = f"  <li><a href='{loc}/index.html'>{loc}</a></li>\n"
+        html = html + link
+
+    html = html + html_footer
+
+    return html
+
+if __name__ == "__main__":
+    html = build_index()
+    with open('index.html', 'w') as index:
+        index.write(html)