From 45574ec7eee642a47939cc23f215d9bd4fe6326a Mon Sep 17 00:00:00 2001 From: Arnas Donauskas Date: Mon, 20 Apr 2026 21:31:50 +0300 Subject: [PATCH] chore: reframe contributor docs fork-first MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit WaCRM is a template — users are expected to fork and customise their own deployment, not to send feature work back upstream. The previous CONTRIBUTING.md read like a standard collaborative-project onboarding guide and set the wrong expectation. Reframed docs: - CONTRIBUTING.md is now "Using WaCRM". Opens with "fork it and make it yours", covers forking + keeping-in-sync commands, explains which PRs do tend to land (security, correctness, docs, small nits) vs. which belong in a fork (new features, stack swaps, opinionated refactors). Keeps the filename so GitHub's built-in "Contributing guidelines" link still surfaces it. - .github/ISSUE_TEMPLATE/feature_request.yml: the intro block now tells the forker up front that feature requests usually become "build it in your fork", and describes the narrow cases where an upstream request is useful. - .github/ISSUE_TEMPLATE/config.yml: adds a third contact link pointing at CONTRIBUTING.md so people see the fork-first framing before filing. - .github/pull_request_template.md: prepends a heads-up that most changes belong in the forker's own repo, with a pointer to CONTRIBUTING.md. Nothing else in the PR changes — CoC, Dependabot, EditorConfig, Prettier configs, issue bug_report.yml, and the package.json changes are orthogonal to the fork-first framing and stay as-is. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/ISSUE_TEMPLATE/config.yml | 3 + .github/ISSUE_TEMPLATE/feature_request.yml | 20 ++- .github/pull_request_template.md | 7 + CONTRIBUTING.md | 152 ++++++++++++++------- 4 files changed, 128 insertions(+), 54 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 7c38ac2..cc84b43 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -6,3 +6,6 @@ contact_links: - name: Setup / "how do I..." questions url: https://github.com/ArnasDon/wacrm/blob/main/docs/README.md about: Check the docs first — setup, deploy, troubleshooting are all covered. + - name: Using WaCRM as a template (forking) + url: https://github.com/ArnasDon/wacrm/blob/main/CONTRIBUTING.md + about: WaCRM is a template. Most changes belong in your fork, not an upstream issue — here's how that works. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index b5b843e..a2cd019 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -6,8 +6,24 @@ body: - type: markdown attributes: value: | - Thanks for the idea. Features with a clear user story and a couple - of alternatives considered tend to move the fastest. + Thanks for the idea — but read this first. + + WaCRM is a **template**, not a collaborative product. The + upstream scope is intentionally narrow, so most feature + requests end up as *"build this in your fork"* rather than + landing here. That's the point of a template. + + When an upstream feature request *is* useful: + + - It fixes a correctness problem in the template. + - It makes the template cleaner for the next forker (reducing + friction, removing footguns). + - It's in scope for "a generic WhatsApp CRM template" rather + than a bet on your specific workflow. + + If the feature is really for your own deployment, fork and + build it there — see + [CONTRIBUTING.md](https://github.com/ArnasDon/wacrm/blob/main/CONTRIBUTING.md). - type: textarea id: problem diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a01bb9e..a978f52 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,11 @@ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba4b5ab..6814637 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,27 @@ -# Contributing to WaCRM +# Using WaCRM -Thanks for the interest. This document is the short version; anything not -answered here, open a draft PR or an issue and we'll figure it out together. +WaCRM is a **template repository**, not a collaborative product. The +expected flow is: -## Before you start +1. **Fork** it to your own GitHub account or organisation. +2. **Deploy** the fork — see [`docs/`](./docs/README.md). +3. **Customise** your fork. Rebrand, add the features you need, remove + the ones you don't, swap hosting, change the schema. -- **Security issues do not belong in public issues** — see - [SECURITY.md](./.github/SECURITY.md) for the private disclosure flow. -- For anything non-trivial, open an issue first so we can agree on the - approach before you write the code. Small fixes and typo-level PRs can - skip this step. +You **don't** need to send changes back upstream. The fact that your +fork diverges is the whole point — the upstream is deliberately +opinionated about stack, UX, and scope, and your fork is where those +opinions become yours. -## Dev loop +## Fork and run ```bash -git clone https://github.com//wacrm.git +# 1. Fork on GitHub: https://github.com/ArnasDon/wacrm → Fork +# 2. Clone your fork +git clone https://github.com//wacrm.git cd wacrm -cp .env.local.example .env.local # fill in your Supabase + Meta creds + +cp .env.local.example .env.local # fill in Supabase + Meta creds npm install npm run dev ``` @@ -24,7 +29,84 @@ npm run dev Full setup (Supabase migrations, WhatsApp Business API, deploy) lives in [`docs/`](./docs/README.md). -### Scripts you'll use +## Keeping your fork up to date + +Pull in upstream bug fixes and security patches periodically: + +```bash +git remote add upstream https://github.com/ArnasDon/wacrm.git # once +git fetch upstream +git checkout main +git merge upstream/main # or: git rebase upstream/main +# Resolve any conflicts (likely in areas you've customised), then push +git push origin main +``` + +If you've made heavy local customisations, rebasing can surface +conflicts every time you pull. Pinning to a specific upstream tag and +updating on your schedule is a valid alternative. + +## Reporting bugs in the upstream template + +If you find a bug in the upstream code — not one you introduced in your +fork — please file it using the +[bug report](https://github.com/ArnasDon/wacrm/issues/new?template=bug_report.yml) +template. Including the commit SHA, the runtime (Hostinger / Vercel / +local / other), and logs will get to a fix fastest. + +## Reporting security issues + +**Do not file security issues publicly.** Follow the private flow in +[SECURITY.md](./.github/SECURITY.md). + +## Upstream pull requests + +Not the primary flow, but welcome in specific cases: + +- **Security fixes** — always welcome, please follow SECURITY.md first + for disclosure. +- **Bug fixes** that match upstream intent (crash, correctness, + documentation errors, typos) — land quickly. +- **Small improvements** (accessibility, obvious UX nits) — usually + welcome, open an issue first to check alignment. + +Less likely to land: + +- **New features.** The template's scope is intentionally narrow. A + "great idea for a CRM" is often a great idea for *your* CRM — i.e. + your fork — but would dilute the template for the next forker. +- **Stack changes** (different ORM, different UI kit, different auth + provider). These belong in a fork, not upstream. +- **Opinionated refactors** without a concrete correctness or + performance motivation. + +If you do send a PR, the usual rules apply: + +- Branch off the latest `main` (don't push to a merged branch — commits + end up orphaned). +- Run `npm run typecheck` and `npm run format` locally first. +- Fill in the PR template, especially the **Test plan**. +- One logical change per PR. +- Commit-message first line is imperative + terse; the body explains + the *why*, the diff shows the *what*. + +Expect a review within a few days. PRs opened without an issue may be +closed — open the issue first to align. + +## If you maintain a public fork + +- Rebrand. The WaCRM name, favicon, and `wacrm.tech` URL belong to the + upstream project; please swap them for your own before putting your + deployment in front of users. +- Keep the MIT [`LICENSE`](./LICENSE) file — that's how the template's + permissions travel with the code. Attribution in a `README` section + is appreciated but not required. +- You are free to re-license additions to your fork however you like. + +## Dev-loop reference + +Even if you never send a PR upstream, these are the scripts you'll use +in your fork: | Command | What it does | | --- | --- | @@ -32,45 +114,11 @@ Full setup (Supabase migrations, WhatsApp Business API, deploy) lives in | `npm run build` | Production build. Next also runs its own typecheck here. | | `npm run typecheck` | `tsc --noEmit`. Fast TS-only pass. | | `npm run lint` | ESLint. | -| `npm run format` | Prettier write. Run before committing. | - -CI on every PR runs lint (non-blocking today), typecheck, and build. - -## PR style - -- **One logical change per PR.** A bug fix and a refactor in the same PR - makes review harder and rollback riskier. -- Branch off the latest `main`. Don't push new commits to a merged branch — - they end up orphaned. -- Commit messages: first line is a short, imperative summary (`fix(inbox): - drop messages on URL change`). Body explains the *why*; the diff shows the - *what*. -- Run `npm run typecheck` and `npm run format` locally before opening the - PR — saves a round trip on CI. -- Fill in the [pull-request template](./.github/pull_request_template.md). A - "Test plan" section the reviewer can actually tick off goes a long way. -- Update relevant docs in [`docs/`](./docs/README.md) when you change - behaviour a forker needs to know about. - -## Code style - -- TypeScript, strict. No `any` unless there's a good reason + a comment. -- Prefer server components; mark client components with `"use client"` only - when they genuinely need interactivity, state, or browser APIs. -- `@/` alias for every internal import. Relative imports are used only - inside the same subfolder. -- No new dependencies without a note in the PR body explaining why; we try - to keep the install lean. - -## Review process - -- @ArnasDon is the sole code owner today (see - [.github/CODEOWNERS](./.github/CODEOWNERS)) and reviews every PR. -- Expect a response within a few days. Friendly ping after a week. -- Reviews are collaborative — "this looks wrong" means "let's talk about - it", not "we're not merging this". +| `npm run format` | Prettier write. | +| `npm run format:check` | Prettier in check-only mode. Useful in CI. | ## Licensing -By contributing, you agree your contribution is licensed under the -[MIT License](./LICENSE), the same license as the rest of the project. +This template is MIT ([`LICENSE`](./LICENSE)). Anything you contribute +upstream is assumed to be MIT too. Your fork's additions are yours to +license however you like.