Skip to content

Commit d55eafa

Browse files
committed
ci(milestone): set the release milestone when an issue or PR closes (#2218)
Problem: milestones stopped being set by hand after #1068, leaving closed issues and pull requests without one. Fix: milestone.yml runs util/milestone.py on `issues: closed`, `pull_request_target: closed` and `workflow_dispatch`. A merged PR or an issue closed as completed gets the open `PyPCAPKit v<major>.<minor>` milestone from the base checkout's `__version__`, read as text; an unmerged PR or a not-planned/duplicate issue loses any milestone. A missing milestone is a warning, never created. A dispatch backfills closed items with no milestone above the previous release milestone's highest number, dry-run by default. The job checks out `github.sha` only, without persisted credentials, under `permissions: {}` plus `contents: read`, `issues: write` and `pull-requests: write` on the job. Test: tests/project/test_milestone_2218.py covers the rule, the title mapping, both modes against a fake REST endpoint, and the workflow's triggers, scopes, base-only checkout and step script.
1 parent 7e8cec0 commit d55eafa

6 files changed

Lines changed: 871 additions & 7 deletions

File tree

‎.github/workflows/milestone.yml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: Milestone
2+
3+
# #2218: sets the release milestone on each issue and pull request as it closes,
4+
# which stopped being done by hand after #1068. The rule is
5+
# util/milestone.py's action_for, documented under "Milestone" in
6+
# docs/source/contributing/workflows.rst: a merged pull request or an issue
7+
# closed as completed gets the open milestone named after the checked-out
8+
# `pcapkit.__version__`; an unmerged pull request or an issue closed as not
9+
# planned loses any milestone. A missing milestone is a warning, never created.
10+
#
11+
# SECURITY. `pull_request_target` gives this run a write token on events a
12+
# stranger can cause, so it must never execute anything the pull request
13+
# supplies. The job below:
14+
#
15+
# * checks out `github.sha`, which under `pull_request_target` is the tip of
16+
# the *base* branch, never the PR head, and only the three files it reads,
17+
# without persisting the token;
18+
# * reads `__version__` from pcapkit/__init__.py as text, importing nothing;
19+
# * takes nothing from the event payload but the item number, passed through
20+
# `env:`, and re-reads the item's state from the API.
21+
#
22+
# tests/project/test_milestone_2218.py asserts each of these over this file.
23+
24+
on:
25+
issues:
26+
types: [closed]
27+
pull_request_target:
28+
types: [closed]
29+
workflow_dispatch:
30+
inputs:
31+
dry_run:
32+
description: Report what the backfill would change, and change nothing
33+
type: boolean
34+
default: true
35+
36+
# The job holds its own scopes.
37+
permissions: {}
38+
39+
# Runs on one item serialize, so a close, reopen and close in quick succession
40+
# is applied in order; each run re-reads the item, so the last one to execute
41+
# writes the final state. A backfill has a group of its own.
42+
concurrency:
43+
group: milestone-${{ (github.event.issue.number || github.event.pull_request.number) && format('item-{0}', github.event.issue.number || github.event.pull_request.number) || 'backfill' }}
44+
cancel-in-progress: false
45+
46+
jobs:
47+
milestone:
48+
name: Set the milestone
49+
runs-on: ubuntu-latest
50+
# One item is a few API calls; a backfill is one listing page per 100 items
51+
# plus one update per item that changed.
52+
timeout-minutes: 10
53+
permissions:
54+
contents: read
55+
issues: write
56+
pull-requests: write
57+
58+
steps:
59+
# The base branch, and only the files the next step reads.
60+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
61+
with:
62+
ref: ${{ github.sha }}
63+
sparse-checkout: |
64+
pcapkit/__init__.py
65+
util/_actions.py
66+
util/milestone.py
67+
sparse-checkout-cone-mode: false
68+
persist-credentials: false
69+
70+
# A dispatch is a dry run unless `dry_run` is unticked.
71+
- name: Set the milestone
72+
env:
73+
GH_TOKEN: ${{ github.token }}
74+
ITEM: ${{ github.event.issue.number || github.event.pull_request.number }}
75+
DRY_RUN: ${{ inputs.dry_run }}
76+
run: |
77+
if [ -n "$ITEM" ]; then
78+
python3 util/milestone.py --item "$ITEM"
79+
elif [ "$DRY_RUN" = 'false' ]; then
80+
python3 util/milestone.py --backfill
81+
else
82+
python3 util/milestone.py --backfill --dry-run
83+
fi

‎docs/source/contributing/conventions/process.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -346,11 +346,13 @@ carrying it are that kind:
346346
Milestones and the Project Board
347347
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
348348

349-
**Milestones are release lines**, titled by minor version (``1.4``, ``1.5``). An issue
350-
or pull request belongs to the line it ships in: the open milestone collects work
351-
targeting the next release, and it is closed when that release's final tag is cut,
349+
**Milestones are release lines**, titled by minor version (``PyPCAPKit v1.4``,
350+
``PyPCAPKit v1.5``). An issue or pull request belongs to the line it ships in: the
351+
open milestone collects work targeting the next release, and it is closed when that release's final tag is cut,
352352
with ``due_on`` set to the tag date. Work closed without shipping -- an unmerged pull
353-
request, an issue closed as not planned -- takes no milestone. The closed milestones
353+
request, an issue closed as not planned -- takes no milestone.
354+
:file:`.github/workflows/milestone.yml` applies this as each item closes, and a manual
355+
run backfills the items closed without one (:doc:`../workflows`). The closed milestones
354356
were backfilled from merge and close dates against the release tags, so an item that
355357
landed just before a tag may sit one line early.
356358

‎docs/source/contributing/workflows.rst‎

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,13 @@ At a Glance
100100
- daily 00:37
101101
- --
102102
- ``issues``, ``pull_request_target``, ``workflow_dispatch``
103+
* - Milestone
104+
- :file:`milestone.yml`
105+
- --
106+
- --
107+
- --
108+
- --
109+
- ``issues``, ``pull_request_target``, ``workflow_dispatch``
103110
* - Coverage Comment
104111
- :file:`coverage-comment.yml`
105112
- --
@@ -183,6 +190,7 @@ than starting a new one.
183190
CT["CI Timing<br/>ci-timing.yml"]
184191
BM["Engine Benchmark<br/>benchmark.yml"]
185192
PS["Project Status<br/>project-status.yml"]
193+
MS["Milestone<br/>milestone.yml"]
186194
CR["Create Release<br/>create-release.yml"]
187195

188196
PUSH --> UT
@@ -227,6 +235,10 @@ than starting a new one.
227235
ISSUES --> PS
228236
PRT --> PS
229237

238+
DISPATCH --> MS
239+
ISSUES --> MS
240+
PRT --> MS
241+
230242
TAG --> CR
231243

232244
classDef trig fill:none,stroke-dasharray:2 2
@@ -553,8 +565,11 @@ release waits for the next Vendor Update on ``main``.
553565
``pull_request_target``
554566
-----------------------
555567

556-
**Project Status** is the only workflow on ``pull_request_target``, and the only one
557-
that runs with a secret on an event a fork can cause: it writes the project board's
568+
**Project Status** and **Milestone** are the workflows on ``pull_request_target``,
569+
which runs the base branch's copy of a workflow with a write token on an event a fork
570+
can cause, so neither runs anything the pull request supplies.
571+
572+
**Project Status** is the one that runs with a secret: it writes the project board's
558573
*Status* field with ``PROJECT_TOKEN``, which a fork's ``pull_request`` run would not
559574
receive. It therefore never checks out the repository and has no ``uses:`` step. It
560575
fetches :file:`util/project_status.py`, and :file:`util/_actions.py`, which it imports
@@ -565,6 +580,45 @@ number from the payload.
565580
secret it skips with a ``::notice::``. The Status mapping it applies is documented in
566581
:doc:`conventions/process`.
567582

583+
**Milestone** writes with ``GITHUB_TOKEN``, scoped to ``issues: write`` and
584+
``pull-requests: write`` on its one job, beside ``contents: read`` for its
585+
checkout. Its checkout is of ``github.sha`` without
586+
persisted credentials, and holds :file:`pcapkit/__init__.py`, :file:`util/milestone.py`
587+
and :file:`util/_actions.py` alone; the version is read from the first as text, so
588+
no code from :mod:`pcapkit` is imported. It takes only the item number from the
589+
payload. ``tests/project/test_milestone_2218.py`` asserts this over the file.
590+
591+
Milestone (:issue:`2218`)
592+
-------------------------------------------------------------------------------
593+
594+
Each issue and pull request gets its release milestone as it closes, by the rule
595+
under "Milestones and the Project Board" in :doc:`conventions/process`, which
596+
``action_for`` in :file:`util/milestone.py` applies:
597+
598+
* a merged pull request, or an issue closed as completed, gets the open milestone
599+
titled ``PyPCAPKit v<major>.<minor>`` from the checked-out ``__version__`` --
600+
``1.5.0b14`` gives ``PyPCAPKit v1.5``;
601+
* a pull request closed unmerged, or an issue closed as not planned or as a
602+
duplicate, loses any milestone it has;
603+
* an issue closed with no reason recorded, or an item reopened before the run reads
604+
it, is left as it is.
605+
606+
The run re-reads the item through the API rather than trusting the event payload.
607+
Where no open milestone has the title, the item is left without one and the run
608+
emits a ``::warning::``: the script never creates a milestone, since opening the
609+
next one is a release step done by hand. A removal needs no milestone, so it goes
610+
ahead regardless.
611+
612+
A ``workflow_dispatch`` backfills: it applies the same rule to every closed item
613+
with no milestone whose number is above the highest-numbered item of the previous
614+
release's milestone, the newest of the ``PyPCAPKit v<major>.<minor>`` milestones
615+
below the current one. Items at or below that bound belong to releases already
616+
made, and those among them without a milestone were left so by hand. With no
617+
earlier milestone to bound it, the backfill warns and changes nothing. Its
618+
``dry_run`` input is ticked by default, so a dispatch reports what it would change
619+
until it is unticked. The ``Set the milestone`` step picks the mode, and runs of one
620+
item share a concurrency group, so a quick close, reopen and close apply in order.
621+
568622
Coverage (:issue:`1063`)
569623
-------------------------------------------------------------------------
570624

‎tests/project/test_actions_helper_2047.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@
4545
HELPER = ROOT / 'util' / '_actions.py'
4646
#: The scripts that import the helper.
4747
SCRIPTS = ('apt_packages', 'check_suite_report', 'ci_timing', 'classify_changes', 'codeql_report',
48-
'coverage_report', 'discussion_report', 'leg_summary', 'pip_install', 'project_status',
48+
'coverage_report', 'discussion_report', 'leg_summary', 'milestone', 'pip_install', 'project_status',
4949
'python_versions', 'regenerate_samples', 'release_conda', 'release_published', 'release_reset_build',
5050
'release_status', 'release_tags', 'release_tiers', 'release_upload', 'superseded',
5151
'update_python_versions', 'vendor_code_changed', 'vendor_test_gate', 'verdict_covers_checkout')
@@ -63,6 +63,7 @@
6363
'coverage_report': (['--help'], {}),
6464
'discussion_report': (['--help'], {}),
6565
'leg_summary': (['ktlo'], {'LEG': 'Python 3.8 (KTLO, non-blocking)', 'STEPS': '{}'}),
66+
'milestone': (['--help'], {}),
6667
'pip_install': (['--help'], {}),
6768
'project_status': (['--help'], {}),
6869
'python_versions': (['latest'], {}),

0 commit comments

Comments
 (0)