From a7ebcdd35909783275fd993e0f572c2ad7d259f7 Mon Sep 17 00:00:00 2001 From: Matthew Bain <66839492+rocketstack-matt@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:08:42 +0100 Subject: [PATCH 1/3] docs: shift project health check to PR-based report with optional AI prompt Make the written health-check report submitted as a PR the primary deliverable instead of a mandatory in-person presentation. Presentation now happens only if the TOC has open questions or concerns on review. Add an optional AI-assisted drafting prompt maintainers may use to produce a first draft of the report. --- project-reports/AI-REPORT-PROMPT.md | 125 ++++++++++++++++++++++++++++ project-reports/README.md | 20 ++--- 2 files changed, 135 insertions(+), 10 deletions(-) create mode 100644 project-reports/AI-REPORT-PROMPT.md diff --git a/project-reports/AI-REPORT-PROMPT.md b/project-reports/AI-REPORT-PROMPT.md new file mode 100644 index 0000000..766f231 --- /dev/null +++ b/project-reports/AI-REPORT-PROMPT.md @@ -0,0 +1,125 @@ +# FINOS Project Health-Check Report — AI-Assisted Drafting Prompt + +This prompt helps FINOS project maintainers produce their semi-annual TOC health-check +report efficiently, with AI assistance. Paste the prompt below into an AI assistant, +filling in the values in the **Inputs** block first. It works best with an agentic +assistant that has web access and the `gh` GitHub CLI (e.g. Claude Code), but a plain +chat assistant can also use it via the FALLBACK path included in the prompt. + +> **Important — this is a drafting aid, not a substitute for maintainer judgement.** +> The assistant produces a *draft* from public GitHub and LFX Insights data. The +> maintainers are expected to **review every section, verify the figures, and amend +> anything that is inaccurate, incomplete, or misframed before raising the PR.** You +> own the final report; the AI only assembles a first pass. +> +> **What happens next:** once the report PR is raised, the TOC reviews it. **If the TOC +> has questions or concerns based on the report, the maintainers will be called to +> present at a TOC meeting.** Reports that are clear and complete may not require a +> presentation — so it is in your interest to make the written report accurate and +> self-explanatory. + +--- + +## Prompt (copy everything below into your AI assistant) + +``` +You are helping me, a maintainer of a FINOS project, draft our semi-annual TOC +health-check report. Produce a complete, accurate first draft that I will then review +and amend before I raise the PR myself. Do not invent figures — every metric must come +from a real source you queried, and you must tell me the source and the exact window +for each number. Where you have to infer or estimate, say so explicitly. + +INPUTS (I have filled these in): +- Project name: [e.g. CALM (Common Architecture Language Model)] +- GitHub repository: [e.g. finos/architecture-as-code] +- LFX Insights URL: [e.g. https://insights.linuxfoundation.org/project/] +- Reporting period: [e.g. 2026 H1 — H1 = Jan–Jun, H2 = Jul–Dec] +- Metrics window: [e.g. trailing 365 days, 2025-06-17 → 2026-06-17] + +STEPS: +1. Fetch the FINOS TOC report TEMPLATE and the process README so you match the required + format exactly: + - Template: https://github.com/finos/technical-oversight-committee/blob/main/project-reports/YYYY-HX-%5BPROJECT-NAME%5D.md + - README: https://github.com/finos/technical-oversight-committee/blob/main/project-reports/README.md + Use `gh api` to read the raw file contents rather than relying on a rendered summary. + Note the filename convention: project-reports//-H-.md. + +2. Gather GitHub metrics for the repository over the metrics window using `gh`: + - PRs opened / merged / currently open + - Issues opened / closed / currently open + - Commits in the window and distinct contributors (merge duplicate identities, e.g. + a person's display name vs their GitHub handle; exclude bots like renovate, + dependabot, github-actions when reporting *human* contribution) + - First-time contributors who joined during the window + - Releases published in the window and the latest release + - Stars / forks; package download counts where the project publishes packages + (e.g. npm: https://api.npmjs.org/downloads/point/:/) + - Maintainer roster: read MAINTAINERS.md if present (note if it is unmerged/draft). + +3. Gather LFX Insights data from the project's LFX URL: active contributors, retention, + contribution concentration (how many contributors / organisations account for >50% + of contributions), merge lead time, issue-resolution time, active days, and the + overall health rating. NOTE: the LFX dashboard is client-rendered, so a simple fetch + may return the same default-window snapshot regardless of the time-range parameter. + If you cannot get genuinely window-specific figures, say so, and where useful derive + trends (e.g. contribution concentration over 90 / 180 / 365 days) directly from git + history instead — and label them as git-derived. + + FALLBACK (if you do NOT have `gh`/CLI or shell access — e.g. a plain chat assistant): + gather the same figures from public web pages instead, and label each number with + where it came from: + - GitHub Insights tabs on the repo: /pulse and /graphs/contributors (contributors, + commit activity), and the Issues and Pull Requests tabs with filters + (e.g. `is:pr is:merged merged:..`) — the result header shows the count. + - Releases page (/releases) for releases in the window and the latest release. + - The repo's MAINTAINERS.md (raw view) for the maintainer roster. + - Package registry pages for downloads (e.g. npmjs.com, or the npm downloads API URL + in step 2, which is a plain GET you can open in a browser). + - The LFX Insights URL for the project's contributor/health metrics. + If you cannot retrieve a given figure, leave it clearly marked as + "[to be filled in by maintainer]" rather than guessing. + +4. Fill in the template section by section, using only the headings the template + defines (Project Overview; Current Status; Community & Contribution Metrics; + Challenges & Blockers; Roadmap & Goals for Next 6 Months; TOC Support Needed; + Additional Information). Keep claims factual and attributable. For the metrics + section, present concrete numbers with their source and window. Highlight notable + adoption (downstream products built on the project), community-depth signals (e.g. + maintainers from organisations beyond the FINOS membership), and any health trends + (improving or worsening) rather than a single snapshot. + +5. Output the finished report as a single markdown file named + -H-.md, ready for me to review. + +6. After the draft, give me a short reviewer checklist of every figure and claim you are + least confident about, and anything I should confirm or correct before I raise the PR. + +CONSTRAINTS: +- This is a draft for my review — I will verify and amend it before raising the PR. +- Be explicit about sources, windows, and any inference or estimation. +- Do not raise the PR yourself. +``` + +--- + +## Metrics window + +The report covers the half-year reporting period (H1 = Jan–Jun, H2 = Jul–Dec), but +quantitative metrics use a **trailing-365-day window** so trends aren't distorted by the +six-month boundary. Label every figure with its source and window. + +--- + +## Maintainer checklist before raising the PR + +- [ ] Every metric checked against its stated source and window. +- [ ] Maintainer list correct and complete (and reconciled with `MAINTAINERS.md`). +- [ ] Accomplishments, roadmap, and TOC-support asks reflect the maintainers' actual view. +- [ ] Challenges/blockers are honest (don't omit known risks). +- [ ] Filename and format match the FINOS template + (`project-reports//-H-.md`). +- [ ] Report is clear and self-explanatory enough to answer likely TOC questions in + writing — remembering the TOC may call you to present if it has questions or concerns. + +Raise the report as a PR to the `project-reports/` folder of +`finos/technical-oversight-committee` at least two weeks before the relevant TOC meeting. diff --git a/project-reports/README.md b/project-reports/README.md index 04df085..9c91196 100644 --- a/project-reports/README.md +++ b/project-reports/README.md @@ -11,19 +11,19 @@ Project reviews are used to: Project reports are to be submitted as a pull request to the `toc/project-reports` under current year folder. -## The Review Process -1. **Assignment & Scheduling:** Check the [Schedule](./SCHEDULE.md) to see upcoming due dates. - * TOC Chair assigns presentation slots during Wednesday's public meetings. - * Each project is assigned a TOC liaison for coordination. - * TOC sends calendar invite to project maintainers using [Email Template](./toc-review-email-template.md). +The health check is centred on a written **report submitted as a pull request** — not a mandatory in-person presentation. Maintainers present to the TOC only when the TOC has questions or concerns that cannot be resolved on the report PR. -2. **Preparation:** The Project maintainers create a report using the [Presentation template](./YYYY-HX-[PROJECT-NAME].md). +1. **Scheduling:** Check the [Schedule](./SCHEDULE.md) to see upcoming due dates. Each project is assigned a TOC liaison for coordination, and the TOC notifies project maintainers of their due date using the [Email Template](./toc-review-email-template.md). -3. **Submission:** Maintainers submit a PR with the report at least **two week** before the meeting. TOC members review and comment on PR. Liaison works with the project to address questions. +2. **Preparation:** The project maintainers create a report using the [report template](./YYYY-HX-[PROJECT-NAME].md). Maintainers may, at their discretion, use the [AI-assisted drafting prompt](./AI-REPORT-PROMPT.md) to produce a first draft — but remain responsible for verifying every figure and amending anything inaccurate before submitting. -4. **Presentation:** The Project maintainers present a 10-15 minutes presentation during the TOC meeting. As part of the agenda, the TOC reviews the project's [LFX Insights](https://insights.lfx.linuxfoundation.org/foundation/finos) data to assess compliance with its maintenance requirements, including the applicable OSPS Baseline maturity level (Maturity Level 2 for Incubating, Maturity Level 3 for Graduated). The report PR will be merged after the presentation. +3. **Submission:** Maintainers submit the report as a PR to the current year's folder at least **two weeks** before the relevant TOC meeting. This report PR is the primary deliverable for the health check. -5. **Post-Presentation:** TOC will discuss any lifecycle transitions or support needs and create a follow-up GitHub issue if needed. +4. **Review:** TOC members review and comment on the PR, and the liaison works with the project to address questions in the PR thread. As part of the review, the TOC assesses the project's [LFX Insights](https://insights.lfx.linuxfoundation.org/foundation/finos) data to evaluate compliance with its maintenance requirements, including the applicable OSPS Baseline maturity level (Maturity Level 2 for Incubating, Maturity Level 3 for Graduated). + +5. **Presentation (only if needed):** If, after reviewing the report, the TOC has open questions or concerns, the project maintainers will be scheduled to present at a future TOC meeting to answer them. A clear, complete written report may remove the need to present at all. The report PR is merged once the TOC is satisfied — after the presentation, if one was required. + +6. **Follow-up:** TOC will discuss any lifecycle transitions or support needs and create a follow-up GitHub issue if needed. ## Instructions for submission @@ -51,7 +51,7 @@ This review process applies to projects in the following lifecycle stages, or pr ## Non-participation and unreachable projects -A project that does not complete its semi-annual review — by not presenting, by not submitting a report, or by having no maintainer of record or none reachable — is recorded as out of compliance with the [presentation maintenance requirement](../operations/processes/projects/incubation.md) for that cycle. Per the lifecycle requirements, three consecutive out-of-compliance reviews qualify a project for archival. +A project that does not complete its semi-annual review — by not submitting a report, by not attending a presentation the TOC has scheduled, or by having no maintainer of record or none reachable — is recorded as out of compliance with the [maintenance requirement](../operations/processes/projects/incubation.md) for that cycle. Per the lifecycle requirements, three consecutive out-of-compliance reviews qualify a project for archival. For a project with no maintainer of record or none reachable, FINOS staff post a notice on the project's issue board requesting confirmation that the project is maintained, with a response deadline (one month, with a reminder one week prior). If no maintainer responds by the deadline, the cycle is recorded as out of compliance and the project is not scheduled to present. From 98788ecb581d21c6184b25125d1f0dc52edd3380 Mon Sep 17 00:00:00 2001 From: Matthew Bain <66839492+rocketstack-matt@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:43:25 +0100 Subject: [PATCH 2/3] docs: align governance, schedule, and notifications with PR-based health check Update the documents that still assumed a mandatory presentation so the process is internally consistent: - incubation.md: maintenance requirement is now report submission, with presentation only if the TOC requests one - activities.md: project health review is conducted from the report PR - governance.md: health review cadence is per project report - SCHEDULE.md: retitled to report schedule; report-centric columns - toc-review-email-template.md: requests a report PR, not a presentation - README.md: title and template references updated --- operations/governance.md | 2 +- operations/processes/activities.md | 7 ++++--- operations/processes/projects/incubation.md | 2 +- project-reports/README.md | 5 ++--- project-reports/SCHEDULE.md | 10 +++++----- project-reports/toc-review-email-template.md | 13 +++++++------ 6 files changed, 20 insertions(+), 19 deletions(-) diff --git a/operations/governance.md b/operations/governance.md index a8025ea..2f5b93c 100644 --- a/operations/governance.md +++ b/operations/governance.md @@ -51,7 +51,7 @@ The key responsibilities of the TOC are summarized below: | | [Lifecycle Criteria](./processes/activities.md#lifecycle-criteria) | May | Chair | | | [Technical Dispute Resolution](./processes/activities.md#technical-dispute-resolution) | As needed | Chair | | | [Cross-project Synergies](./processes/activities.md#cross-project-synergies) | Routine | Vice Chair or Volunteer | -| | [Project Health Review](./processes/activities.md#project-health-review) | Semi-annual (per project presentation) | Vice Chair or Volunteer | +| | [Project Health Review](./processes/activities.md#project-health-review) | Semi-annual (per project report) | Vice Chair or Volunteer | | | [Lifecycle Transitions](./processes/activities.md#lifecycle-transitions) | As needed | Vice Chair or Volunteer | | **Landscape Growth** | | | [Contribution Review](./processes/activities.md#contribution-review) | As needed | Chair & Volunteer | diff --git a/operations/processes/activities.md b/operations/processes/activities.md index 6e1cf56..21563fa 100644 --- a/operations/processes/activities.md +++ b/operations/processes/activities.md @@ -40,12 +40,13 @@ The following activities are part of the TOC's collective responsibilities, as d ## Project Health Review - **Responsible Party**: TOC Vice Chair -- **Outcome**: Review each project's health at its semi-annual presentation and recommend actions as necessary +- **Outcome**: Review each project's health from its semi-annual report and recommend actions as necessary - **Process**: - - During each project's semi-annual presentation (see [project-reports](../../project-reports/README.md)), review the project's [LFX Insights](https://insights.lfx.linuxfoundation.org/foundation/finos) data to assess compliance with its maintenance requirements, including the applicable OSPS Baseline maturity level + - When reviewing each project's semi-annual health-check report PR (see [project-reports](../../project-reports/README.md)), review the project's [LFX Insights](https://insights.lfx.linuxfoundation.org/foundation/finos) data to assess compliance with its maintenance requirements, including the applicable OSPS Baseline maturity level + - Where the TOC has open questions or concerns, schedule the project to present at a TOC meeting to answer them - Record projects found out of compliance, and the support offered - Track follow-up actions through GitHub Issues - - The TOC may additionally review a project's Insights data between presentations if concerns arise + - The TOC may additionally review a project's Insights data between reports if concerns arise ## Landscape Evolution diff --git a/operations/processes/projects/incubation.md b/operations/processes/projects/incubation.md index 57eeb11..7538a43 100644 --- a/operations/processes/projects/incubation.md +++ b/operations/processes/projects/incubation.md @@ -23,5 +23,5 @@ The following must remain true for _Incubating_ projects at all times. A Health - Publicly visible adherence to a project roadmap - Pre-release integration with a FINOS-approved dependency and license scanner - Build and release processes do not use any private or undocumented steps -- Presentation at a public TOC meeting at least once every six months +- Submission of a semi-annual health-check report as a pull request, and presentation at a public TOC meeting if the TOC requests one after reviewing the report - Demonstrated adherence to **Maturity Level 2** of the [Open Source Project Security Baseline](https://baseline.openssf.org/) diff --git a/project-reports/README.md b/project-reports/README.md index 9c91196..ff32fdd 100644 --- a/project-reports/README.md +++ b/project-reports/README.md @@ -1,4 +1,4 @@ -# TOC Project Review & Presentation Reports +# TOC Project Health-Check Reports These reviews are required for **every FINOS project** to ensure transparency, health, alignment with the FINOS mission, and governance. @@ -27,8 +27,7 @@ The health check is centred on a written **report submitted as a pull request** ## Instructions for submission -1. **Copy the Template:** Start by copying the [Presentation template](./YYYY-HX-[PROJECT-NAME].md) -file as +1. **Copy the Template:** Start by copying the [report template](./YYYY-HX-[PROJECT-NAME].md). 2. **Name the File:** Save the new file in the current year's folder using the following convention: diff --git a/project-reports/SCHEDULE.md b/project-reports/SCHEDULE.md index d183f2d..73d713b 100644 --- a/project-reports/SCHEDULE.md +++ b/project-reports/SCHEDULE.md @@ -1,7 +1,7 @@ -# FINOS Project Presentation Schedule +# FINOS Project Health-Check Report Schedule ### Frequency: **Every 6 Months** -| Cycle | Coverage | Presentation Window | +| Cycle | Coverage | Report Window | |-------|----------|--------------------| | H1 | Jan–Jun | Feb-Apr | | H2 | Jul–Dec | Aug–Oct | @@ -9,13 +9,13 @@ ## 2026 Schedule ### H1 2026 -| Project Name | Last Presented | Next Due | Status | Notes | +| Project Name | Last Reported | Next Due | Status | Notes | |---------|----------------|----------|--------|-------| | Project A | [date] | [date] | Scheduled | Review Summary | | Project B | [date] | [date] | Due Soon | Review Summary | ### H2 2026 -| Project Name | Last Presented | Next Due | Status | Notes | +| Project Name | Last Reported | Next Due | Status | Notes | |---------|----------------|----------|--------|-------| | Project A | [date] | [date] | Scheduled | Review Summary | @@ -25,4 +25,4 @@ - Overdue - Completed & Archived -> **TOC Chair/Vice Chair will update this table after each presentation or schedule confirmation.** +> **TOC Chair/Vice Chair will update this table after each report review or schedule confirmation.** diff --git a/project-reports/toc-review-email-template.md b/project-reports/toc-review-email-template.md index 5d7707d..b39aa04 100644 --- a/project-reports/toc-review-email-template.md +++ b/project-reports/toc-review-email-template.md @@ -1,19 +1,20 @@ -Subject: [Reminder] FINOS TOC Semi-Annual Project Presentation Due [Project Name] +Subject: [Reminder] FINOS TOC Semi-Annual Health-Check Report Due [Project Name] Hello [Project Maintainers], -Your project [Project Name] is due for its semi-annual presentation to the FINOS TOC. +Your project [Project Name] is due for its semi-annual health-check report to the FINOS TOC. **Action Required:** -1. Review project report template -2. Submit your report via PR -3. Prepare a 15-minute presentation covering the key points +1. Review the project report template (optionally use the AI-assisted drafting prompt) +2. Submit your report as a PR at least two weeks before the relevant TOC meeting + +The report PR is the primary deliverable. The TOC will review it and may follow up with questions in the PR. Only if the TOC has open questions or concerns will you be scheduled to present at a future TOC meeting. **Your TOC Liaison:** [Name] ([email]) **Resources:** - Report template: [link] -- Meeting join link: [link] +- AI-assisted drafting prompt: [link] Please confirm receipt within 2 weeks. Please let us know if you have any questions. From db55ba21881722dd989392b76a2a0b0b0f0d1ad2 Mon Sep 17 00:00:00 2001 From: Matthew Bain <66839492+rocketstack-matt@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:55:58 +0100 Subject: [PATCH 3/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- project-reports/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project-reports/README.md b/project-reports/README.md index ff32fdd..720d9b9 100644 --- a/project-reports/README.md +++ b/project-reports/README.md @@ -9,7 +9,7 @@ Project reviews are used to: # Submitting Project Updates -Project reports are to be submitted as a pull request to the `toc/project-reports` under current year folder. +Project reports are to be submitted as a pull request under the `project-reports/[Year]/` folder for the current year. The health check is centred on a written **report submitted as a pull request** — not a mandatory in-person presentation. Maintainers present to the TOC only when the TOC has questions or concerns that cannot be resolved on the report PR.