Merge pull request #230 from Promptly-Technologies-LLC/auto-merge/main-to-stripe-20260714213411

Propagate main to stripe

Author: chriscarrollsmith

.github/workflows/test.yml

@@ -2,7 +2,6 @@ name: Test
 
 on:
   push:
-    branches: [main, stripe]
   pull_request:
     branches: [main, stripe]
   workflow_dispatch:

README.md

@@ -34,6 +34,25 @@ The template also includes full-featured secure auth with:
 - Password recovery flow
 - Role-based access control system
 
+## Optional branches
+
+Some capabilities are maintained on dedicated branches so `main` stays lean:
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Core template (auth, orgs, RBAC) |
+| [`stripe`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/stripe) | Organization-scoped Stripe billing |
+| [`modal`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/modal) | Modal.com deployment artifacts |
+| [`hetzner`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/hetzner) | Hetzner Cloud deployment artifacts |
+
+New SaaS forks can start from `stripe`, or merge it later:
+
+```bash
+git remote add upstream https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp.git
+git fetch upstream stripe
+git merge upstream/stripe
+```
+
 ## Design Philosophy
 
 The design philosophy of the template is to prefer low-level,

user_guide/04-customization.qmd

@@ -44,6 +44,8 @@ git fetch upstream stripe
 git merge upstream/stripe
 ```
 
+When merging, expect conflicts in shared core files such as `main.py`, `pyproject.toml`, `utils/core/db.py`, `routers/core/organization.py`, header/organization templates, `tests/conftest.py`, and `.env.example`. Resolve by keeping billing additions from `stripe` while preserving your fork-specific changes.
+
 ### Testing
 
 The project uses Pytest for unit testing. It's highly recommended to write and run tests before committing code to ensure nothing is broken!

user_guide/05-deployment.qmd

@@ -13,6 +13,8 @@ There are *many* hosting options available for each of these services; this guid
 
 ::: {.callout-note}
 Deployment artifacts (Dockerfiles, deploy scripts, compose files, etc.) are kept on separate git branches — one per deployment target — to avoid cluttering the main branch. See the `modal` branch for Modal deployment files and the `hetzner` branch for Hetzner Cloud deployment files. The documentation below describes how to use them.
+
+Optional organization-scoped Stripe billing (Checkout, Customer Portal, webhooks) lives on the [`stripe`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/stripe) branch — not on `main`. Deploy billing-enabled apps from `stripe` (or after merging it into your fork); see `user_guide/07-billing.qmd` on that branch for setup.
 :::
 
 ## Deploying and Configuring the FastAPI App

user_guide/06-contributing.qmd

@@ -43,6 +43,10 @@ To contribute code to the project:
    - Provide a clear description of the changes
    - Link to any related issues
 
+### Optional branches
+
+Core template changes on `main` propagate automatically to `modal`, `hetzner`, and `stripe` via CI. Pull requests to `main` that touch shared files (`main.py`, `pyproject.toml`, `utils/core/db.py`, `routers/core/organization.py`, templates, `tests/conftest.py`, `.env.example`) may need manual conflict resolution when those changes are merged into `stripe`. See the [customization guide](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/user-guide/customization.html) for the `git merge upstream/stripe` recipe.
+
 ### Rendering the documentation
 
 The documentation website is built with [Great Docs](https://posit-dev.github.io/great-docs/). If you make changes to the `.qmd` files in the `user_guide/` folder, you will need to rebuild the docs with Great Docs.