docs: branch model + migration-to-org guide + PR-template target hint
Operator + contributor docs for the post-org-move world. None of these files reference the legacy branch names (`beta` / old `main` meaning) — they describe the new shape (`main` = active dev, `stable` = curated release channel), so they're correct from the moment the rename happens. Three additions/edits: 1. `docs/migration-to-org.md` (new) — operator-facing one-pager that the in-app migration banner + the OLD GHCR package URLs (now 404) can point at. Walks through the single `docker-compose.yml` edit needed. 2. `CONTRIBUTING.md` — new "Branch model" section explaining which branch to target (`main` for features + most fixes; `stable` only for small, surgical bugfix backports). Updates the "fork from beta" step to "fork from main". Updates the release-process paragraph to describe the two-channel model instead of the old beta→main promote. 3. `.github/PULL_REQUEST_TEMPLATE.md` — adds a target-branch hint at the top of the template (HTML comment so it shows during PR composition but doesn't render in the merged PR body).
This commit is contained in:
Paul Nothaft
+24
-3
@@ -38,7 +38,7 @@ Unsure where to begin? You can start by looking through these issues:
|
||||
|
||||
### Pull Requests
|
||||
|
||||
1. **Fork the repo** and create your branch from `beta`
|
||||
1. **Fork the repo** and create your branch from `main` (active development)
|
||||
2. **Install dependencies**:
|
||||
```bash
|
||||
cd backend && npm install
|
||||
@@ -153,11 +153,32 @@ picpeak/
|
||||
│ └── public/ # Static assets
|
||||
```
|
||||
|
||||
## 🌿 Branch model
|
||||
|
||||
PicPeak runs on two long-lived branches:
|
||||
|
||||
| Branch | Role | What targets it |
|
||||
|---|---|---|
|
||||
| **`main`** | Active development. The next release is being assembled here. | Feature PRs. Most bugfix PRs. |
|
||||
| **`stable`** | Curated release channel. Production-recommended. | Urgent bugfix backports only — small, surgical PRs that land cleanly without dragging in unrelated changes. |
|
||||
|
||||
### Which branch should my PR target?
|
||||
|
||||
- **New feature** → target `main`.
|
||||
- **Bugfix that ONLY affects active dev** → target `main`.
|
||||
- **Bugfix that current stable users need** → open a small PR against `main`, AND a separate small PR against `stable` with the same change. Keep both surgical so each lands cleanly.
|
||||
|
||||
**Hard rule on PR scope**: bugfix PRs against `stable` must be small enough to backport without conflict. Omnibus PRs (e.g. five unrelated sub-features) are fine for `main`, but never for `stable` — they make the next `main → stable` merge painful and break the "stable is always shippable" invariant.
|
||||
|
||||
If you're not sure which branch to target, default to `main` and a maintainer will retarget during review.
|
||||
|
||||
## 🔄 Release Process
|
||||
|
||||
Releases are cut from the `beta` branch (rolling beta) and promoted to `main` (stable) on a 4–6 week cadence. `release-please` handles version bumps, changelog generation, and Docker image publication automatically — contributors don't update `package.json` or `CHANGELOG.md` by hand.
|
||||
Releases are cut independently from `main` (pre-release versions for the active channel) and `stable` (semver releases for the curated channel). `release-please` handles version bumps, changelog generation, and Docker image publication automatically — contributors don't update `package.json` or `CHANGELOG.md` by hand.
|
||||
|
||||
See [RELEASING.md](RELEASING.md) for the full operational doc (promotion criteria, conflict-resolution checklist for the beta→main merge, hotfix backport path, versioning rules).
|
||||
Periodic `main → stable` merges promote a batch of `main` work to the stable channel. The maintainer chooses when (typically every ~4 weeks, sooner if a hot bug demands it).
|
||||
|
||||
See [RELEASING.md](RELEASING.md) for the full operational doc (promotion criteria, conflict-resolution checklist for the `main → stable` merge, hotfix backport path, versioning rules).
|
||||
|
||||
## 📮 Contact
|
||||
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# Migration: PicPeak moved to its own GitHub organization
|
||||
|
||||
PicPeak's repository moved from the maintainer's personal handle to a dedicated
|
||||
GitHub organization. This is a one-time, operator-facing change. The software
|
||||
itself is unchanged; only the URLs you pull images from have moved.
|
||||
|
||||
## TL;DR — what changed and what you need to do
|
||||
|
||||
| | Before | After |
|
||||
|---|---|---|
|
||||
| **Repository URL** | `github.com/the-luap/picpeak` | `github.com/PicPeak/picpeak` |
|
||||
| **Docker images** | `ghcr.io/the-luap/picpeak/{backend,frontend}` | `ghcr.io/picpeak/picpeak/{backend,frontend}` |
|
||||
| **Branches (active dev)** | `beta` | `main` |
|
||||
| **Branches (stable channel)** | `main` | `stable` |
|
||||
|
||||
**Action required**: update your `docker-compose.yml` to pull from
|
||||
`ghcr.io/picpeak/picpeak/{backend,frontend}`. The old path no longer serves
|
||||
images.
|
||||
|
||||
## Why this changed
|
||||
|
||||
The repo lived under a personal GitHub handle since the project began. Moving to
|
||||
an organization is a one-time housekeeping step that:
|
||||
|
||||
- Separates the project's identity from any individual maintainer's account.
|
||||
- Lets the project add additional maintainers later without re-transferring.
|
||||
- Matches the convention every other open-source project uses for branch names
|
||||
(`main` = active development, `stable` = curated production channel).
|
||||
|
||||
## docker-compose.yml — exact edit
|
||||
|
||||
Find these two lines:
|
||||
|
||||
```yaml
|
||||
image: ghcr.io/the-luap/picpeak/backend:${PICPEAK_CHANNEL:-stable}
|
||||
# ...
|
||||
image: ghcr.io/the-luap/picpeak/frontend:${PICPEAK_CHANNEL:-stable}
|
||||
```
|
||||
|
||||
Replace with:
|
||||
|
||||
```yaml
|
||||
image: ghcr.io/picpeak/picpeak/backend:${PICPEAK_CHANNEL:-stable}
|
||||
# ...
|
||||
image: ghcr.io/picpeak/picpeak/frontend:${PICPEAK_CHANNEL:-stable}
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
That's it. No data migration, no config changes, no database changes.
|
||||
|
||||
## What auto-redirects (you don't have to change)
|
||||
|
||||
GitHub redirects the old repo URL indefinitely, so these all keep working:
|
||||
|
||||
- Browser links to `github.com/the-luap/picpeak/...` (issues, PRs, files)
|
||||
- `git clone https://github.com/the-luap/picpeak.git`
|
||||
- GitHub API calls to `api.github.com/repos/the-luap/picpeak/...`
|
||||
|
||||
Worth updating to the canonical `PicPeak/picpeak` form when convenient, but
|
||||
nothing breaks if you don't.
|
||||
|
||||
## What does NOT auto-redirect
|
||||
|
||||
- **GHCR image paths.** `ghcr.io/the-luap/picpeak/*` returns **404** — you must
|
||||
update your compose file.
|
||||
|
||||
## Branch rename
|
||||
|
||||
The active-development branch was renamed from `beta` → `main`, and the previous
|
||||
`main` (stable channel) was renamed to `stable`. This matches the convention
|
||||
every other open-source project uses.
|
||||
|
||||
If you're a contributor:
|
||||
|
||||
- **Feature PRs**: target `main`.
|
||||
- **Bugfix PRs**: target `main`. If the fix also needs to ship to current stable
|
||||
users, open a separate small PR against `stable`.
|
||||
|
||||
If you're an operator: ignore. Branch names don't affect pulls.
|
||||
|
||||
## Got stuck?
|
||||
|
||||
Open an issue at https://github.com/PicPeak/picpeak/issues with the error
|
||||
message and we'll help.
|
||||
Reference in New Issue
Block a user