diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 0000000..0c1b3ca --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,30 @@ +name: Stale drafts +on: + schedule: + # Arbitrary time, to avoid GitHub's peak-load scheduling delays. + - cron: "41 5 * * *" + workflow_dispatch: +permissions: + contents: read +concurrency: + group: stale-drafts + cancel-in-progress: false +jobs: + stale: + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + actions: read # lets hestia detect evicted cache entries upfront + contents: read + issues: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: DeterminateSystems/nix-installer-action@3138316df39ed29be04236d7ffc686fa525866aa # v23 + - uses: Mic92/hestia@dfed9ced335d28978ba74e513939a10db1f71025 # v3.1.0 + with: + # Do not upload paths that cache.nixos.org already serves. + upstream-cache-filter: true + - name: Open issues for drafts that go stale within a week + run: nix run --no-update-lock-file .#stale-drafts -- . + env: + GH_TOKEN: ${{ github.token }} diff --git a/contrib/book.py b/contrib/book.py index 1cf9b79..00146ca 100644 --- a/contrib/book.py +++ b/contrib/book.py @@ -42,10 +42,11 @@ def frontmatter(text): def check(name, text): - """A page must have a type and a status, and a draft the instant from - which it is stale, where OKF makes both optional. Whether that instant - has passed is not checked, so that a build does not depend on when it - runs.""" + """Returns the frontmatter of a page, a draft's stale_after as a + datetime. A page must have a type and a status, and a draft the instant + from which it is stale, where OKF makes both optional. Whether that + instant has passed is not checked, so that a build does not depend on + when it runs.""" try: fields = frontmatter(text) except (yaml.YAMLError, ValueError) as e: @@ -66,6 +67,8 @@ def check(name, text): raise ValueError( f"{name}: a draft needs stale_after, an ISO 8601 instant with an offset" ) + fields["stale_after"] = stale_after + return fields def summary(index, pages): @@ -99,15 +102,22 @@ def contents(index): return "# Contents\n\n" + body +def read_pages(docs): + """The text of each page in `docs` but the reserved ones, by its path + relative to `docs`.""" + return { + page.relative_to(docs).as_posix(): page.read_text() + for page in sorted(docs.rglob("*.md")) + if page.name not in RESERVED + } + + def assemble(root): docs, out = root / DOCS, root / SRC index = (docs / "index.md").read_text() - pages = {} - for page in sorted(docs.rglob("*.md")): - if page.name not in RESERVED: - name = page.relative_to(docs).as_posix() - pages[name] = page.read_text() - check(name, pages[name]) + pages = read_pages(docs) + for name, text in pages.items(): + check(name, text) # docs/README.md directs readers of the repository to the book; as a # chapter it would overwrite the introduction. pages.pop("README.md", None) diff --git a/contrib/stale.py b/contrib/stale.py new file mode 100644 index 0000000..57484b8 --- /dev/null +++ b/contrib/stale.py @@ -0,0 +1,72 @@ +#!/usr/bin/env python3 +"""Open an issue for each draft chapter that goes stale within a week. + +A chapter gets no second issue while the first word of an open one's +title is its path, nor an issue titled like a closed one, so closing the +issue without moving the chapter's stale_after leaves it closed. Stubs +are skipped: a stub's draft is under review on its pull request's +branch, so its stale_after does not date anything in docs/. + + GH_TOKEN=... python3 stale.py ROOT +""" + +import argparse +import json +import subprocess +from datetime import datetime, timedelta, timezone +from pathlib import Path + +import book + +NOTICE = timedelta(days=7) + + +def issues(pages, existing, now): + """The title and body of an issue for each of `pages` that is a draft, + not a stub, stale before `now + NOTICE` and not yet raised in + `existing`, the issues as `gh issue list --json title,state` gives + them.""" + out = [] + for name, text in pages.items(): + fields = book.check(name, text) + if fields["status"] != "draft" or fields["type"] == "Stub": + continue + stale_after = fields["stale_after"] + path = f"{book.DOCS}/{name}" + title = f"{path} goes stale on {stale_after:%Y-%m-%d}" + if stale_after - now > NOTICE or any( + i["title"] == title + or (i["state"] == "OPEN" and i["title"].partition(" ")[0] == path) + for i in existing + ): + continue + out.append( + ( + title, + f"`{path}` is a draft to be treated as possibly outdated from " + f"{stale_after.isoformat()}. Review it, then move its " + "`stale_after` later or change its `status`.", + ) + ) + return out + + +def gh(*args): + return subprocess.run( + ["gh", *args], check=True, capture_output=True, text=True + ).stdout + + +def main(argv=None): + p = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + p.add_argument("root", type=Path) + root = p.parse_args(argv).root + listed = gh("issue", "list", "--state=all", "--limit=1000", "--json=title,state") + pages = book.read_pages(root / book.DOCS) + now = datetime.now(timezone.utc) + for title, body in issues(pages, json.loads(listed), now): + print(gh("issue", "create", "--title", title, "--body", body), end="") + + +if __name__ == "__main__": + main() diff --git a/contrib/test_stale.py b/contrib/test_stale.py new file mode 100644 index 0000000..7f8e56b --- /dev/null +++ b/contrib/test_stale.py @@ -0,0 +1,63 @@ +from datetime import datetime, timezone + +import pytest +import stale + +NOW = datetime(2027, 4, 8, tzinfo=timezone.utc) + + +def page(kind, status, stale_after=None): + line = f"stale_after: {stale_after}\n" if stale_after else "" + return f"---\ntype: {kind}\nstatus: {status}\n{line}---\n" + + +@pytest.mark.parametrize( + "stale_after", ["2027-04-15T00:00:00Z", "2027-04-01T00:00:00Z"] +) +def test_a_draft_stale_within_a_week_or_already_gets_an_issue(stale_after): + [(title, body)] = stale.issues( + {"a.md": page("Chapter", "draft", stale_after)}, [], NOW + ) + assert title == f"docs/a.md goes stale on {stale_after[:10]}" + assert "`docs/a.md`" in body and stale_after[:10] in body + + +@pytest.mark.parametrize( + "text", + [ + page("Chapter", "draft", "2027-04-15T00:00:01Z"), + page("Stub", "draft", "2027-04-15T00:00:00Z"), + page("Chapter", "stable"), + ], +) +def test_no_issue_for_a_later_draft_a_stub_or_a_stable_page(text): + assert stale.issues({"a.md": text}, [], NOW) == [] + + +def titles(existing): + pages = { + name: page("Chapter", "draft", "2027-04-10T00:00:00Z") + for name in ("a.md", "ab.md") + } + return [t for t, _ in stale.issues(pages, existing, NOW)] + + +@pytest.mark.parametrize("title", ["docs/a.md goes stale on 2027-01-01", "docs/a.md"]) +def test_no_second_issue_while_one_is_open_for_the_chapter(title): + existing = [{"title": title, "state": "OPEN"}] + assert titles(existing) == ["docs/ab.md goes stale on 2027-04-10"] + + +def test_a_closed_issue_is_not_reopened_until_stale_after_moves(): + closed = [{"title": "docs/a.md goes stale on 2027-04-10", "state": "CLOSED"}] + assert titles(closed) == ["docs/ab.md goes stale on 2027-04-10"] + moved = [{"title": "docs/a.md goes stale on 2027-01-01", "state": "CLOSED"}] + assert titles(moved) == [ + "docs/a.md goes stale on 2027-04-10", + "docs/ab.md goes stale on 2027-04-10", + ] + + +def test_an_invalid_page_fails_the_run(): + with pytest.raises(ValueError, match="stale_after"): + stale.issues({"a.md": page("Chapter", "draft")}, [], NOW) diff --git a/flake.nix b/flake.nix index c0e75f6..848b529 100644 --- a/flake.nix +++ b/flake.nix @@ -20,6 +20,7 @@ ./nix/devshell.nix ./nix/spellcheck.nix ./nix/apps/validate-commits + ./nix/apps/stale-drafts ]; }; } diff --git a/nix/apps/stale-drafts/default.nix b/nix/apps/stale-drafts/default.nix new file mode 100644 index 0000000..d072f14 --- /dev/null +++ b/nix/apps/stale-drafts/default.nix @@ -0,0 +1,22 @@ +{ + perSystem = + { pkgs, ... }: + let + stale-drafts = pkgs.writeShellApplication { + name = "stale-drafts"; + runtimeInputs = [ + (pkgs.python3.withPackages (ps: [ ps.pyyaml ])) + pkgs.gh + ]; + text = ''python3 ${../../../contrib}/stale.py "$@"''; + }; + in + { + packages.stale-drafts = stale-drafts; + apps.stale-drafts = { + type = "app"; + program = "${stale-drafts}/bin/stale-drafts"; + meta.description = "Open an issue for each draft that goes stale within a week"; + }; + }; +}