Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/stale.yml
Original file line number Diff line number Diff line change
@@ -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
Comment thread
bc1cindy marked this conversation as resolved.
Resolved
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 }}
30 changes: 20 additions & 10 deletions contrib/book.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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):
Expand Down Expand Up @@ -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)
Expand Down
72 changes: 72 additions & 0 deletions contrib/stale.py
Original file line number Diff line number Diff line change
@@ -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()
63 changes: 63 additions & 0 deletions contrib/test_stale.py
Original file line number Diff line number Diff line change
@@ -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)
1 change: 1 addition & 0 deletions flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
./nix/devshell.nix
./nix/spellcheck.nix
./nix/apps/validate-commits
./nix/apps/stale-drafts
];
};
}
22 changes: 22 additions & 0 deletions nix/apps/stale-drafts/default.nix
Original file line number Diff line number Diff line change
@@ -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";
};
};
}
Loading