tenseleyflow/shithub / 925e659

Browse files

docs: Pro v1 user-tier billing + per-feature enforce matrix

Authored by mfwolffe <wolffemf@dukes.jmu.edu>
SHA
925e65958ea475423da1cc148f8f4a0453e2a8db
Parents
f2cacca
Tree
71f92ac

4 changed files

StatusFile+-
M CHANGELOG.md 18 0
M docs/internal/billing.md 52 0
M docs/public/SUMMARY.md 1 0
A docs/public/user/billing.md 59 0
CHANGELOG.mdmodified
@@ -12,6 +12,24 @@ between minor releases.
1212
1313
 ### Added
1414
15
+- **Personal Pro tier feature gates (PRO07).** Pro v1 lights up four
16
+  user-tier paygates ratified in PRO01: required reviewers on private
17
+  personal repos, multi-reviewer thresholds, advanced branch
18
+  protection (prevent force-push / deletion / require signed commits),
19
+  and profile pins above the Free cap of 6 (Pro raises this to 100).
20
+  Each gate is enforced via a per-feature operator flag in
21
+  `billing.enforce.*` so launches are reversible without a code
22
+  rollback. PRO07 ships dark (all flags default false) and operators
23
+  flip each feature on after the 7-day report-only telemetry soak.
24
+  Pro user accounts retain existing required-reviewer rules and pin
25
+  configuration through cancellation; the gate refuses to create new
26
+  gated state on Free but never deletes prior data. Added the
27
+  `FeatureProfilePinsBeyondFree` (user-only) and
28
+  `FeatureCodeOwnersReview` (placeholder; no-op enforce until the
29
+  CODEOWNERS parser ships) entitlement constants, plus the
30
+  `LimitProfilePinsFreeCap` / `LimitProfilePinsProCap` limit
31
+  constants. Migration `0076_profile_pins_pro_cap` raises the
32
+  `profile_pins.position` check constraint from `1..6` to `1..100`.
1533
 - **REST API contract (S50 §0).** `GET /api/v1/meta` returns the
1634
   server's version stamp and a list of feature capability strings
1735
   for client-side feature detection. Every `/api/v1/*` response
docs/internal/billing.mdmodified
@@ -87,6 +87,58 @@ Rules for paid-org copy:
8787
 | Data residency/compliance | Deferred | Deferred | Later Enterprise feature |
8888
 | Billing support | Basic instance support | Billing support after runbook exists | Contact sales |
8989
90
+## Pro v1 user-tier matrix (PRO07)
91
+
92
+Pro is the user-tier paid plan (single seat, $4/month). PRO01 ratified
93
+the v1 feature set; PRO07 wires the enforcement matrix. CODEOWNERS is a
94
+registered placeholder with a no-op enforce path until the parser ships.
95
+
96
+| Capability | Free | Pro |
97
+| --- | --- | --- |
98
+| Public/private personal repos | Included | Included |
99
+| Required reviewers on private personal repos | Upgrade | Included |
100
+| Multi-reviewer (>1 approvals) on private personal repos | Upgrade | Included |
101
+| Advanced branch protection on private personal repos | Upgrade | Included |
102
+| CODEOWNERS review | Deferred | Deferred |
103
+| Profile pins | 6 | 100 |
104
+
105
+Multi-reviewer is **not** a separate feature constant — the numeric
106
+threshold lives in the deny payload of `FeatureRequiredReviewers`.
107
+
108
+### Per-feature enforcement flags
109
+
110
+PRO05 plumbed user-kind report-only logging through every gating site.
111
+PRO07 lights up the gates one feature at a time via
112
+`billing.enforce.*` in the operator's config. Defaults are all false
113
+(report-only). Each flag is a one-way deploy that operators can roll
114
+back without code changes.
115
+
116
+| Config key | Gate site | Default |
117
+| --- | --- | --- |
118
+| `billing.enforce.user_required_reviewers` | `internal/web/handlers/repo/settings_branches.go` | false |
119
+| `billing.enforce.user_advanced_branch_protection` | `internal/web/handlers/repo/settings_branches.go` | false |
120
+| `billing.enforce.user_profile_pins_beyond_free` | `internal/web/handlers/profile/pins.go` | false |
121
+
122
+Rollout discipline:
123
+
124
+1. Deploy with all flags false. Run the report-only telemetry query
125
+   for 7 days. Confirm zero unexpected user-kind would-denies.
126
+2. Flip one feature flag in staging. Soak 7 days.
127
+3. Flip the same feature flag in production.
128
+4. Repeat per feature.
129
+
130
+PRO07's pitfall doc explicitly forbids enforcing a feature without an
131
+unenforce path. New gating sites land with their own flag; do not
132
+share flags across features.
133
+
134
+### Downgrade preservation
135
+
136
+`users.plan = 'free'` after cancellation grandfather's existing gated
137
+state — required-reviewer rules, profile pins above 6, advanced flags
138
+on existing rules. The gate refuses to **create** new gated state on
139
+Free, but never deletes prior configuration. This is the same
140
+contract as the org-tier downgrade.
141
+
90142
 ## Current capability audit
91143
92144
 Already present and safe to gate:
docs/public/SUMMARY.mdmodified
@@ -11,6 +11,7 @@
1111
 - [Account settings](./user/account.md)
1212
   - [Two-factor authentication](./user/2fa.md)
1313
   - [GPG keys & commit signing](./user/gpg-keys.md)
14
+  - [Pro for personal accounts](./user/billing.md)
1415
 - [Issues](./user/issues.md)
1516
 - [Pull requests](./user/pull-requests.md)
1617
   - [Branch protection & reviews](./user/branch-protection.md)
docs/public/user/billing.mdadded
@@ -0,0 +1,59 @@
1
+# Pro for personal accounts
2
+
3
+Pro is shithub's single-seat paid plan for personal accounts. It
4
+unlocks a small set of features beyond what Free offers, charged at
5
+$4 / month and managed entirely through the Stripe Billing Portal.
6
+
7
+Upgrade, downgrade, and invoice management live at
8
+[`/settings/billing`](../user/account.md).
9
+
10
+## What Pro unlocks
11
+
12
+| Feature | Free | Pro |
13
+|---|---|---|
14
+| Public and private repositories | Included | Included |
15
+| Required reviewers on private personal repos | Upgrade | Included |
16
+| Multi-reviewer (>1 approvals) on private personal repos | Upgrade | Included |
17
+| Advanced branch protection on private personal repos | Upgrade | Included |
18
+| Pinned repositories on your profile | Up to 6 | Up to 100 |
19
+
20
+"Advanced branch protection" covers preventing force-pushes,
21
+preventing deletion, and requiring signed commits on private personal
22
+repos. Basic protection (an empty rule, or one with none of those
23
+flags) stays on Free.
24
+
25
+## What stays on Free
26
+
27
+- Public and private repositories — no count limits.
28
+- Org features (Team plan) — Pro applies to your *personal* account.
29
+  Organizations have a separate Team tier with its own feature set.
30
+- Issues, pull requests, Actions minutes, Storage — none of these are
31
+  gated by Pro today. Pro v1 is intentionally small.
32
+
33
+## Downgrading
34
+
35
+Cancellation flows through the Stripe Billing Portal. shithub honors
36
+the scheduled cancellation: at the end of the paid period your
37
+account returns to Free.
38
+
39
+- Existing required-reviewer rules and advanced branch protection
40
+  flags stay in the database. The gate refuses to **create** new
41
+  gated state on Free, but never deletes prior configuration.
42
+- Profile pins above 6 stay in place — you keep what you pinned as
43
+  Pro; the cap re-applies when you next edit your pins.
44
+
45
+## Payment failures
46
+
47
+A past-due subscription enters a grace period (operator-configured;
48
+the default is 14 days). Pro features stay available during grace.
49
+After grace lapses, Pro-only features become read-only until billing
50
+is brought back into good standing.
51
+
52
+## Operator note
53
+
54
+Each Pro feature gate has an independent operator-controlled enforce
55
+flag in `billing.enforce.*`. Until an operator flips a feature on,
56
+its gate runs in report-only mode — Free users continue to use the
57
+feature, the would-deny is logged for the soak. This page describes
58
+the **eventual** Pro behavior; deployment-specific timing depends on
59
+your operator's per-feature rollout schedule.