From 98de47105f49f5a23e39f648f9714b7f4157acc3 Mon Sep 17 00:00:00 2001 From: Leo Chen Date: Tue, 19 May 2026 14:12:03 -0700 Subject: [PATCH 1/4] feat: add CODEOWNERS file and documentation for branch protection rules --- .github/CODEOWNERS | 29 +++++++++++++++++++ .../CODEOWNERS_and_branch_protection.md | 29 +++++++++++++++++++ docs/operations/README.md | 20 +++++++------ 3 files changed, 69 insertions(+), 9 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 docs/operations/CODEOWNERS_and_branch_protection.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..17bf532 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,29 @@ +# CODEOWNERS — last matching pattern wins; keep broad paths first, then specifics. +# GitHub: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +# +# Only these handles: @snowfox1003 @jonathanMLDev +# Per-app primary owners below are placeholders (round-robin); replace when the team agrees. + +* @snowfox1003 + +boost_collector_runner/ @snowfox1003 +cppa_user_tracker/ @snowfox1003 +github_activity_tracker/ @snowfox1003 +boost_library_tracker/ @snowfox1003 +boost_library_docs_tracker/ @jonathanMLDev +boost_library_usage_dashboard/ @jonathanMLDev +boost_usage_tracker/ @jonathanMLDev +boost_mailing_list_tracker/ @jonathanMLDev +cppa_pinecone_sync/ @jonathanMLDev +clang_github_tracker/ @snowfox1003 +cppa_slack_tracker/ @snowfox1003 +discord_activity_tracker/ @snowfox1003 +wg21_paper_tracker/ @snowfox1003 +cppa_youtube_script_tracker/ @jonathanMLDev +slack_event_handler/ @snowfox1003 + +core/ @snowfox1003 @jonathanMLDev + +.github/workflows/ @snowfox1003 + +docs/ @snowfox1003 @jonathanMLDev diff --git a/docs/operations/CODEOWNERS_and_branch_protection.md b/docs/operations/CODEOWNERS_and_branch_protection.md new file mode 100644 index 0000000..64fa24e --- /dev/null +++ b/docs/operations/CODEOWNERS_and_branch_protection.md @@ -0,0 +1,29 @@ +# CODEOWNERS and branch protection + +This repo uses [`.github/CODEOWNERS`](../../.github/CODEOWNERS) so GitHub can request reviews from code owners. **CODEOWNERS only affects behavior meaningfully when branch protection requires reviews from code owners** (and owners have write access to the repository). + +## 1. Enable branch protection (repository admin) + +For each protected branch (for example `main` or `develop`): + +1. Open **Settings → Branches → Branch protection rules** (or **Rules → Rulesets** if your org uses rulesets). +2. Edit the rule that applies to the branch (or create one). +3. Enable **Require a pull request before merging**. +4. Enable **Require an approval from a code owner** (wording may be **Require review from Code Owners**). +5. Set **Required number of approvals before merging** to **1** (or your team policy). With `docs/` listing multiple owners, one approval from any listed owner for the changed paths is usually enough. + +Without step 4, owners may still appear as suggested reviewers, but merges are not blocked on owner review. + +## 2. Verify after CODEOWNERS is on the default branch + +GitHub reads `CODEOWNERS` from the **default** branch for review assignment. After your PR that adds or updates `.github/CODEOWNERS` is **merged**: + +1. **App path:** open a **draft** PR that changes one file under a single app (e.g. `boost_mailing_list_tracker/`). Confirm the **Reviewers** section lists the owner from the matching `CODEOWNERS` line. +2. **`docs/`:** open a draft PR that only changes a file under `docs/`. Confirm all handles on the `docs/` line are requested (users with write access only). +3. **Workflows:** open a draft PR that only changes a file under `.github/workflows/`. Confirm the expected owner is requested. + +Then close or merge the draft PRs as appropriate. + +## 3. Updating owners + +When primary owners change, edit [`.github/CODEOWNERS`](../../.github/CODEOWNERS) only. Optionally align the human ↔ app table in [Onboarding.md](../Onboarding.md) or [cross-app-dependencies.md](../cross-app-dependencies.md) so docs stay in sync. diff --git a/docs/operations/README.md b/docs/operations/README.md index 33f729b..b3c83e8 100644 --- a/docs/operations/README.md +++ b/docs/operations/README.md @@ -1,13 +1,15 @@ -# Operations (shared I/O layer) +# Operations -**Operations** are shared, app-agnostic layers for **external I/O** (GitHub API, Discord, notifications, etc.). Any Django app can use them; they are **not** part of the per-app **service API** (which is for database writes only). +**Operations** are shared, app-agnostic helpers under **`core/operations/`** for talking to the outside world (GitHub, Discord, CLIs, and similar). They are **not** the per-app **service API**, which is reserved for **database** writes. -| Operation | Package | Doc | Purpose | -|-----------|---------|-----|---------| -| **GitHub** | `core.operations.github_ops` | [github.md](github.md) | Clone, push, fetch file, create PR/issue/comment; token resolution. | -| **DiscordChatExporter** | *(external CLI)* | [discord_chat_exporter.md](discord_chat_exporter.md) | Download, install path, `.env` settings for Tyrrrz CLI used by `discord_activity_tracker`. | -| **Discord** | *(planned)* | *(e.g. discord.md)* | Send notifications to Discord; used by other apps. | +| Name | Where it lives | Doc | Role | +|------|----------------|-----|------| +| GitHub | `core.operations.github_ops` | [github.md](github.md) | Clone, fetch, PR/issue/comment helpers; tokens. | +| DiscordChatExporter | External CLI | [discord_chat_exporter.md](discord_chat_exporter.md) | Install, paths, and `.env` for the exporter used by `discord_activity_tracker`. | +| Discord | *(planned)* | — | Notifications to Discord from multiple apps. | -**When to add a new operation:** When multiple apps need the same external integration (e.g. “notify via Discord”). Prefer adding a **utility package** under **`core/operations/`** (not a new Django app unless you need models), document it in this folder, then list it in the table above. +**Repo runbooks:** [CODEOWNERS & branch protection](CODEOWNERS_and_branch_protection.md) — code owners file and GitHub branch settings. -**Service API vs Operations:** Service API = one place per app for **database** create/update/delete. Operations = shared **external** I/O (GitHub, Discord, etc.) used by many apps. +**Adding a new operation:** Put shared integration code in **`core/operations/`**, document it here, and add a row to the table (use a new Django app only if you need models). + +**Service API vs operations:** *Service API* = one module per app for ORM create/update/delete. *Operations* = shared external I/O any app may import. From 378f3a147c7f49b45abd0b4b0b9e554d653900f3 Mon Sep 17 00:00:00 2001 From: Leo Chen Date: Tue, 19 May 2026 14:27:02 -0700 Subject: [PATCH 2/4] chore: update CODEOWNERS to include on more as a code owner for various trackers and workflows --- .github/CODEOWNERS | 41 ++++++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 17bf532..2e4bd2e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,29 +1,28 @@ # CODEOWNERS — last matching pattern wins; keep broad paths first, then specifics. # GitHub: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners # -# Only these handles: @snowfox1003 @jonathanMLDev +# Only these handles: @snowfox1003 @jonathanMLDev @wpak-ai # Per-app primary owners below are placeholders (round-robin); replace when the team agrees. -* @snowfox1003 +* @snowfox1003 @wpak-ai -boost_collector_runner/ @snowfox1003 -cppa_user_tracker/ @snowfox1003 -github_activity_tracker/ @snowfox1003 -boost_library_tracker/ @snowfox1003 -boost_library_docs_tracker/ @jonathanMLDev -boost_library_usage_dashboard/ @jonathanMLDev -boost_usage_tracker/ @jonathanMLDev -boost_mailing_list_tracker/ @jonathanMLDev -cppa_pinecone_sync/ @jonathanMLDev -clang_github_tracker/ @snowfox1003 -cppa_slack_tracker/ @snowfox1003 -discord_activity_tracker/ @snowfox1003 -wg21_paper_tracker/ @snowfox1003 -cppa_youtube_script_tracker/ @jonathanMLDev -slack_event_handler/ @snowfox1003 +boost_collector_runner/ @snowfox1003 @wpak-ai +cppa_user_tracker/ @snowfox1003 @wpak-ai +github_activity_tracker/ @snowfox1003 @wpak-ai +boost_library_tracker/ @snowfox1003 @wpak-ai +boost_library_docs_tracker/ @jonathanMLDev @wpak-ai +boost_library_usage_dashboard/ @jonathanMLDev @wpak-ai +boost_usage_tracker/ @jonathanMLDev @wpak-ai +boost_mailing_list_tracker/ @jonathanMLDev @wpak-ai +cppa_pinecone_sync/ @jonathanMLDev @wpak-ai +clang_github_tracker/ @snowfox1003 @wpak-ai +cppa_slack_tracker/ @snowfox1003 @wpak-ai +discord_activity_tracker/ @snowfox1003 @wpak-ai +wg21_paper_tracker/ @snowfox1003 @wpak-ai +cppa_youtube_script_tracker/ @jonathanMLDev @wpak-ai +slack_event_handler/ @snowfox1003 @wpak-ai -core/ @snowfox1003 @jonathanMLDev +core/ @snowfox1003 @jonathanMLDev @wpak-ai +.github/workflows/ @snowfox1003 @wpak-ai -.github/workflows/ @snowfox1003 - -docs/ @snowfox1003 @jonathanMLDev +docs/ @snowfox1003 @jonathanMLDev @wpak-ai \ No newline at end of file From 3a77c62dd5961dc12ae9048f27a5e80e74ebce57 Mon Sep 17 00:00:00 2001 From: Leo Chen Date: Tue, 19 May 2026 15:56:05 -0700 Subject: [PATCH 3/4] Fix lint error --- .github/CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 2e4bd2e..1aff752 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -25,4 +25,4 @@ slack_event_handler/ @snowfox1003 @wpak-ai core/ @snowfox1003 @jonathanMLDev @wpak-ai .github/workflows/ @snowfox1003 @wpak-ai -docs/ @snowfox1003 @jonathanMLDev @wpak-ai \ No newline at end of file +docs/ @snowfox1003 @jonathanMLDev @wpak-ai From a17dc9dd867862ad2930084280098c8fb0ba2f0d Mon Sep 17 00:00:00 2001 From: Leo Chen Date: Wed, 20 May 2026 08:44:45 -0700 Subject: [PATCH 4/4] docs: add CODEOWNERS and branch protection documentation --- docs/{operations => }/CODEOWNERS_and_branch_protection.md | 4 ++-- docs/operations/README.md | 3 --- 2 files changed, 2 insertions(+), 5 deletions(-) rename docs/{operations => }/CODEOWNERS_and_branch_protection.md (75%) diff --git a/docs/operations/CODEOWNERS_and_branch_protection.md b/docs/CODEOWNERS_and_branch_protection.md similarity index 75% rename from docs/operations/CODEOWNERS_and_branch_protection.md rename to docs/CODEOWNERS_and_branch_protection.md index 64fa24e..a311270 100644 --- a/docs/operations/CODEOWNERS_and_branch_protection.md +++ b/docs/CODEOWNERS_and_branch_protection.md @@ -1,6 +1,6 @@ # CODEOWNERS and branch protection -This repo uses [`.github/CODEOWNERS`](../../.github/CODEOWNERS) so GitHub can request reviews from code owners. **CODEOWNERS only affects behavior meaningfully when branch protection requires reviews from code owners** (and owners have write access to the repository). +This repo uses [`.github/CODEOWNERS`](../.github/CODEOWNERS) so GitHub can request reviews from code owners. **CODEOWNERS only affects behavior meaningfully when branch protection requires reviews from code owners** (and owners have write access to the repository). ## 1. Enable branch protection (repository admin) @@ -26,4 +26,4 @@ Then close or merge the draft PRs as appropriate. ## 3. Updating owners -When primary owners change, edit [`.github/CODEOWNERS`](../../.github/CODEOWNERS) only. Optionally align the human ↔ app table in [Onboarding.md](../Onboarding.md) or [cross-app-dependencies.md](../cross-app-dependencies.md) so docs stay in sync. +When primary owners change, edit [`.github/CODEOWNERS`](../.github/CODEOWNERS) only. Optionally align the human ↔ app table in [Onboarding.md](Onboarding.md) or [cross-app-dependencies.md](cross-app-dependencies.md) so docs stay in sync. diff --git a/docs/operations/README.md b/docs/operations/README.md index b3c83e8..0929d69 100644 --- a/docs/operations/README.md +++ b/docs/operations/README.md @@ -6,9 +6,6 @@ |------|----------------|-----|------| | GitHub | `core.operations.github_ops` | [github.md](github.md) | Clone, fetch, PR/issue/comment helpers; tokens. | | DiscordChatExporter | External CLI | [discord_chat_exporter.md](discord_chat_exporter.md) | Install, paths, and `.env` for the exporter used by `discord_activity_tracker`. | -| Discord | *(planned)* | — | Notifications to Discord from multiple apps. | - -**Repo runbooks:** [CODEOWNERS & branch protection](CODEOWNERS_and_branch_protection.md) — code owners file and GitHub branch settings. **Adding a new operation:** Put shared integration code in **`core/operations/`**, document it here, and add a row to the table (use a new Django app only if you need models).