diff --git a/README.md b/README.md index 2ff2659..41dfef1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Reproducible studies on architecture governance, review friction, and ADR-driven The studies website is published at: -- https://studies.archgate.dev +- https://docs.archgate.dev The site uses Astro + Starlight, so studies are written in Markdown/MDX instead of hand-crafted HTML. diff --git a/astro.config.mjs b/astro.config.mjs index e00d21e..d3f45f9 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -2,7 +2,7 @@ import starlight from "@astrojs/starlight"; import { defineConfig } from "astro/config"; export default defineConfig({ - site: "https://studies.archgate.dev", + site: "https://docs.archgate.dev", integrations: [ starlight({ title: "Archgate Studies", diff --git a/public/CNAME b/public/CNAME index 6ef80c6..ae579be 100644 --- a/public/CNAME +++ b/public/CNAME @@ -1 +1 @@ -studies.archgate.dev +docs.archgate.dev diff --git a/studies/sentry-pr-review-friction/README.md b/studies/sentry-pr-review-friction/README.md index 314a20e..36d69f4 100644 --- a/studies/sentry-pr-review-friction/README.md +++ b/studies/sentry-pr-review-friction/README.md @@ -6,7 +6,7 @@ Evidence-based analysis of review friction in `getsentry/sentry`. This study col The study is published as a multi-page article at: -- [studies.archgate.dev/studies/sentry-pr-review-friction](https://studies.archgate.dev/studies/sentry-pr-review-friction/) +- [docs.archgate.dev/studies/sentry-pr-review-friction](https://docs.archgate.dev/studies/sentry-pr-review-friction/) Source files are in `src/content/docs/studies/sentry-pr-review-friction/`. diff --git a/studies/sentry-pr-review-friction/proposed-adrs/BE-001-api-contract-evolution.md b/studies/sentry-pr-review-friction/proposed-adrs/BE-001-api-contract-evolution.md index 4688cbf..58218cb 100644 --- a/studies/sentry-pr-review-friction/proposed-adrs/BE-001-api-contract-evolution.md +++ b/studies/sentry-pr-review-friction/proposed-adrs/BE-001-api-contract-evolution.md @@ -8,7 +8,7 @@ files: ["src/sentry/**/*.py", "src/sentry/options/**/*.py", "src/sentry/api/seri ## Context -The [Sentry PR Friction Study](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) identified **API design and defaults** as the top discussion theme — appearing in **38.3%** of high-friction PRs in the deep comment sample. Reviewers repeatedly debate: +The [Sentry PR Friction Study](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) identified **API design and defaults** as the top discussion theme — appearing in **38.3%** of high-friction PRs in the deep comment sample. Reviewers repeatedly debate: - Whether new fields should be nullable or required with defaults - How defaults propagate across scopes (org → project → runtime) @@ -221,7 +221,7 @@ Code reviewers MUST verify: ## References -- [Sentry PR Friction Study — Themes](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) -- [Sentry PR Friction Study — Automated Review (Pattern 4: Type System Misuse)](https://studies.archgate.dev/studies/sentry-pr-review-friction/automated-review/) +- [Sentry PR Friction Study — Themes](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) +- [Sentry PR Friction Study — Automated Review (Pattern 4: Type System Misuse)](https://docs.archgate.dev/studies/sentry-pr-review-friction/automated-review/) - [PR #111697](https://github.com/getsentry/sentry/pull/111697) — primary evidence source: 47 review events, multiple bot findings about option keys and Pydantic Literals - [GEN-003 Bot Finding Promotion](./GEN-003-bot-finding-promotion.md) — Companion ADR establishing the workflow that produced this rule diff --git a/studies/sentry-pr-review-friction/proposed-adrs/BE-002-security-review-protocol.md b/studies/sentry-pr-review-friction/proposed-adrs/BE-002-security-review-protocol.md index c9b55e3..61ddd2a 100644 --- a/studies/sentry-pr-review-friction/proposed-adrs/BE-002-security-review-protocol.md +++ b/studies/sentry-pr-review-friction/proposed-adrs/BE-002-security-review-protocol.md @@ -8,7 +8,7 @@ files: ["src/sentry/integrations/**/*.py", "src/sentry/identity/**/*.py", "src/s ## Context -The [Sentry PR Friction Study](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) found that **security and permissions** discussion appears in **20.0%** of high-friction PRs — a lower frequency than other themes, but with disproportionately high stakes. The `github` scope has the highest median review count (5.5) of any scope in the codebase, almost entirely due to security surface area in OAuth and pipeline code. +The [Sentry PR Friction Study](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) found that **security and permissions** discussion appears in **20.0%** of high-friction PRs — a lower frequency than other themes, but with disproportionately high stakes. The `github` scope has the highest median review count (5.5) of any scope in the codebase, almost entirely due to security surface area in OAuth and pipeline code. Specific bot and human findings from the study: @@ -215,7 +215,7 @@ Code reviewers MUST verify: ## References -- [Sentry PR Friction Study — Themes (Security)](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) +- [Sentry PR Friction Study — Themes (Security)](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) - [PR #111728](https://github.com/getsentry/sentry/pull/111728) — primary evidence: 32 review events on GitHub OAuth pipeline security - [PR #111663](https://github.com/getsentry/sentry/pull/111663) — defense-in-depth weakening detection - [PR #111499](https://github.com/getsentry/sentry/pull/111499) — missing UI permission checks diff --git a/studies/sentry-pr-review-friction/proposed-adrs/FE-001-frontend-component-conventions.md b/studies/sentry-pr-review-friction/proposed-adrs/FE-001-frontend-component-conventions.md index c90e073..4f9cf2a 100644 --- a/studies/sentry-pr-review-friction/proposed-adrs/FE-001-frontend-component-conventions.md +++ b/studies/sentry-pr-review-friction/proposed-adrs/FE-001-frontend-component-conventions.md @@ -8,7 +8,7 @@ files: ["static/app/**/*.tsx", "static/app/**/*.ts", "static/gsApp/**/*.tsx", "s ## Context -The [Sentry PR Friction Study](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) found that **component patterns and styling** appears in **35.0%** of high-friction PRs. The single most repeated review comment in the entire dataset is: +The [Sentry PR Friction Study](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) found that **component patterns and styling** appears in **35.0%** of high-friction PRs. The single most repeated review comment in the entire dataset is: > "Can we avoid this inline style w/ prop of some kind?" @@ -247,7 +247,7 @@ Code reviewers MUST verify: ## References -- [Sentry PR Friction Study — Themes (Component Patterns)](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) +- [Sentry PR Friction Study — Themes (Component Patterns)](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) - [PR #111529](https://github.com/getsentry/sentry/pull/111529) — six identical "no inline style" review comments in one PR - [PR #111490](https://github.com/getsentry/sentry/pull/111490) — form state stuck in loading after error - [Custom ESLint plugin (proposed)](../proposed-lint-rules/eslint-frontend-conventions.js) — edit-time enforcement diff --git a/studies/sentry-pr-review-friction/proposed-adrs/GEN-001-pr-scope-boundaries.md b/studies/sentry-pr-review-friction/proposed-adrs/GEN-001-pr-scope-boundaries.md index 70b1cfa..9288848 100644 --- a/studies/sentry-pr-review-friction/proposed-adrs/GEN-001-pr-scope-boundaries.md +++ b/studies/sentry-pr-review-friction/proposed-adrs/GEN-001-pr-scope-boundaries.md @@ -8,14 +8,14 @@ files: ["**/*"] ## Context -Analysis of 500 merged PRs in `getsentry/sentry` over a 90-day window (see the [Sentry PR Friction study](https://studies.archgate.dev/studies/sentry-pr-review-friction/baseline/)) shows that PR size is the strongest predictor of review friction: +Analysis of 500 merged PRs in `getsentry/sentry` over a 90-day window (see the [Sentry PR Friction study](https://docs.archgate.dev/studies/sentry-pr-review-friction/baseline/)) shows that PR size is the strongest predictor of review friction: - **Small PRs** (≤3 files, ≤80 churn): median TTM 1.66h, median 1 review event, 12.6% high-friction rate - **Large PRs** (≥10 files OR ≥400 churn): median TTM 22.52h, median 5 review events, **57.4% high-friction rate** Large PRs are 13.6x slower to merge and 4.6x more likely to land in the high-friction quartile. Feature PRs (`feat`) compound this — they hit 38.6% high friction vs 17.6% for fix PRs. -The [abandoned PR analysis](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/) further shows that abandoned high-discussion PRs and merged high-friction PRs have the same median file count (4 files). The friction comes from approach disagreement bundled into a single review surface, not from size alone — but size makes bundling more likely. +The [abandoned PR analysis](https://docs.archgate.dev/studies/sentry-pr-review-friction/abandoned/) further shows that abandoned high-discussion PRs and merged high-friction PRs have the same median file count (4 files). The friction comes from approach disagreement bundled into a single review surface, not from size alone — but size makes bundling more likely. **Alternatives considered:** @@ -142,6 +142,6 @@ Code reviewers MUST verify: ## References -- [Sentry PR Friction Study — Baseline Metrics](https://studies.archgate.dev/studies/sentry-pr-review-friction/baseline/) -- [Sentry PR Friction Study — Abandoned PRs](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/) +- [Sentry PR Friction Study — Baseline Metrics](https://docs.archgate.dev/studies/sentry-pr-review-friction/baseline/) +- [Sentry PR Friction Study — Abandoned PRs](https://docs.archgate.dev/studies/sentry-pr-review-friction/abandoned/) - [GEN-002 Test Evidence Matrix](./GEN-002-test-evidence-matrix.md) — Companion ADR for per-change-type test expectations diff --git a/studies/sentry-pr-review-friction/proposed-adrs/GEN-002-test-evidence-matrix.md b/studies/sentry-pr-review-friction/proposed-adrs/GEN-002-test-evidence-matrix.md index 7fe8ed6..8f1046f 100644 --- a/studies/sentry-pr-review-friction/proposed-adrs/GEN-002-test-evidence-matrix.md +++ b/studies/sentry-pr-review-friction/proposed-adrs/GEN-002-test-evidence-matrix.md @@ -8,7 +8,7 @@ files: ["src/**/*.py", "src/**/*.ts", "src/**/*.tsx", "static/**/*.tsx"] ## Context -The [Sentry PR Friction Study](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) found that **test evidence and coverage** is tied for the top discussion theme — appearing in **38.3%** of high-friction PRs. The pattern is striking: reviewers are not asking authors to "add more tests" in the abstract. They are asking for **specific tests** that the author didn't think to write: +The [Sentry PR Friction Study](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) found that **test evidence and coverage** is tied for the top discussion theme — appearing in **38.3%** of high-friction PRs. The pattern is striking: reviewers are not asking authors to "add more tests" in the abstract. They are asking for **specific tests** that the author didn't think to write: - Rendering tests that verify provider context propagation ([#111554](https://github.com/getsentry/sentry/pull/111554)) - Error path tests for circuit breakers when the underlying request fails ([#111723](https://github.com/getsentry/sentry/pull/111723)) @@ -171,8 +171,8 @@ Code reviewers MUST verify: ## References -- [Sentry PR Friction Study — Themes (Test Evidence)](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) -- [Sentry PR Friction Study — Automated Review Pattern 4 (Test correctness)](https://studies.archgate.dev/studies/sentry-pr-review-friction/automated-review/) +- [Sentry PR Friction Study — Themes (Test Evidence)](https://docs.archgate.dev/studies/sentry-pr-review-friction/themes/) +- [Sentry PR Friction Study — Automated Review Pattern 4 (Test correctness)](https://docs.archgate.dev/studies/sentry-pr-review-friction/automated-review/) - [PR #111554](https://github.com/getsentry/sentry/pull/111554) — context propagation test gap - [PR #111723](https://github.com/getsentry/sentry/pull/111723) — circuit breaker error path test gap - [PR #111697](https://github.com/getsentry/sentry/pull/111697) — test assertion mismatch (passing for wrong reason) diff --git a/studies/sentry-pr-review-friction/proposed-adrs/GEN-003-bot-finding-promotion.md b/studies/sentry-pr-review-friction/proposed-adrs/GEN-003-bot-finding-promotion.md index 12e1f58..55fb891 100644 --- a/studies/sentry-pr-review-friction/proposed-adrs/GEN-003-bot-finding-promotion.md +++ b/studies/sentry-pr-review-friction/proposed-adrs/GEN-003-bot-finding-promotion.md @@ -8,7 +8,7 @@ files: [] ## Context -Sentry runs three automated reviewers on its PRs: `sentry[bot]` (bug prediction), `sentry-warden[bot]` (correctness/security checking), and `cursor[bot]` (Cursor's agentic review). The [Sentry PR Friction Study](https://studies.archgate.dev/studies/sentry-pr-review-friction/automated-review/) found that: +Sentry runs three automated reviewers on its PRs: `sentry[bot]` (bug prediction), `sentry-warden[bot]` (correctness/security checking), and `cursor[bot]` (Cursor's agentic review). The [Sentry PR Friction Study](https://docs.archgate.dev/studies/sentry-pr-review-friction/automated-review/) found that: - Bot reviewers account for **23.7%** of substantive review comments - **68.3%** of high-friction PRs have bot review activity @@ -88,7 +88,7 @@ A quarterly meeting reviews: - File a `bot-finding-promotion` ticket when a category crosses the recurrence threshold - Suppress the bot category when the deterministic check ships, to avoid double-flagging - Treat the bots as **discovery** tools, not as front-line review -- Refer back to the [Sentry PR Friction Study automated review page](https://studies.archgate.dev/studies/sentry-pr-review-friction/automated-review/) for the initial pattern catalog +- Refer back to the [Sentry PR Friction Study automated review page](https://docs.archgate.dev/studies/sentry-pr-review-friction/automated-review/) for the initial pattern catalog ### Don't @@ -154,7 +154,7 @@ This ADR is a workflow ADR with no companion `.rules.ts` file. Enforcement is pr ## References -- [Sentry PR Friction Study — Automated Review](https://studies.archgate.dev/studies/sentry-pr-review-friction/automated-review/) — Full pattern catalog and cost analysis +- [Sentry PR Friction Study — Automated Review](https://docs.archgate.dev/studies/sentry-pr-review-friction/automated-review/) — Full pattern catalog and cost analysis - [BE-001 API Contract Evolution](./BE-001-api-contract-evolution.md) — Promotion target for option/serializer findings - [FE-001 Frontend Component Conventions](./FE-001-frontend-component-conventions.md) — Promotion target for inline-style and form-state findings - [BE-002 Security Review Protocol](./BE-002-security-review-protocol.md) — Promotion target for defense-in-depth findings diff --git a/studies/sentry-pr-review-friction/proposed-lint-rules/README.md b/studies/sentry-pr-review-friction/proposed-lint-rules/README.md index 485b5aa..3e0747d 100644 --- a/studies/sentry-pr-review-friction/proposed-lint-rules/README.md +++ b/studies/sentry-pr-review-friction/proposed-lint-rules/README.md @@ -1,6 +1,6 @@ # Proposed Lint Rules for Sentry -This folder contains custom lint plugin rules that complement the [proposed ADRs](../proposed-adrs/). They target the recurring bot finding patterns identified in the [Sentry PR Friction Study](https://studies.archgate.dev/studies/sentry-pr-review-friction/automated-review/). +This folder contains custom lint plugin rules that complement the [proposed ADRs](../proposed-adrs/). They target the recurring bot finding patterns identified in the [Sentry PR Friction Study](https://docs.archgate.dev/studies/sentry-pr-review-friction/automated-review/). ## Where these would live in Sentry diff --git a/studies/sentry-pr-review-friction/proposed-lint-rules/eslint-frontend-conventions.js b/studies/sentry-pr-review-friction/proposed-lint-rules/eslint-frontend-conventions.js index eecdddd..c537936 100644 --- a/studies/sentry-pr-review-friction/proposed-lint-rules/eslint-frontend-conventions.js +++ b/studies/sentry-pr-review-friction/proposed-lint-rules/eslint-frontend-conventions.js @@ -5,7 +5,7 @@ * Styling Conventions) for the Sentry codebase. * * Implements the patterns that recur across PRs in the Sentry PR Friction - * Study (https://studies.archgate.dev/studies/sentry-pr-review-friction/): + * Study (https://docs.archgate.dev/studies/sentry-pr-review-friction/): * * - no-inline-style: forbids `style={...}` JSX attributes without an * `// inline-style:` escape hatch comment diff --git a/studies/sentry-pr-review-friction/proposed-lint-rules/semgrep-doesnotexist.yaml b/studies/sentry-pr-review-friction/proposed-lint-rules/semgrep-doesnotexist.yaml index aecaebd..6128481 100644 --- a/studies/sentry-pr-review-friction/proposed-lint-rules/semgrep-doesnotexist.yaml +++ b/studies/sentry-pr-review-friction/proposed-lint-rules/semgrep-doesnotexist.yaml @@ -9,7 +9,7 @@ # "If project_id is None in trigger_coding_agent_launch, Project.objects.get_from_cache fails silently" # (and several similar instances across the Sentry PR Friction Study sample) # -# Source: https://studies.archgate.dev/studies/sentry-pr-review-friction/automated-review/ +# Source: https://docs.archgate.dev/studies/sentry-pr-review-friction/automated-review/ rules: - id: missing-doesnotexist-handler