mrsumanbiswas · Nov 7, 2026 · Nov 7, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,63 @@
+name: Bug report
+description: Something in the app or server doesn't work as expected
+title: "[BUG]: "
+labels: ["bug", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! For security problems, please use [private reporting](https://github.com/CommandLineCoding/Elephant/security/advisories/new) instead.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Where does it happen?
+      options:
+        - Mobile app
+        - Server / API
+        - Encryption (keys, safety numbers, "can't decrypt")
+        - Build, CI or deployment
+        - Not sure
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you see, and what did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Open a chat
+        2. Long-press a message and tap Edit
+        3. ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: App version
+      description: You → Help & about shows it.
+      placeholder: "0.3.2"
+  - type: input
+    id: device
+    attributes:
+      label: Device and Android version
+      placeholder: "Pixel 7, Android 15"
+  - type: dropdown
+    id: server
+    attributes:
+      label: Server
+      options:
+        - Elephant Cloud
+        - Self-hosted
+        - Not applicable
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or screenshots
+      description: Optional. `adb logcat | grep flutter` output or server logs help a lot. Remove anything private first.
+      render: text
diff --git a/.github/ISSUE_TEMPLATE/but_report.md b/.github/ISSUE_TEMPLATE/but_report.md
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,5 +1,11 @@
 blank_issues_enabled: false
 contact_links:
   - name: Ask a question
-    url: https://github.com/CommandLineCoding/elephant/discussions/new
-    about: Please ask your questions in our discussions area.
+    url: https://github.com/CommandLineCoding/Elephant/discussions/categories/q-a
+    about: Setup help, "how do I…", or anything you're unsure about.
+  - name: Share an idea
+    url: https://github.com/CommandLineCoding/Elephant/discussions/categories/ideas
+    about: Talk through an idea before turning it into a feature request.
+  - name: Report a security vulnerability
+    url: https://github.com/CommandLineCoding/Elephant/security/advisories/new
+    about: Please report vulnerabilities privately, not as a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,43 @@
+name: Feature request
+description: Suggest an idea or improvement
+title: "[FEAT]: "
+labels: ["enhancement", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Not sure it's a fit yet? Start a thread in [Discussions → Ideas](https://github.com/CommandLineCoding/Elephant/discussions/categories/ideas) first.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the situation, not the solution, e.g. "I can't tell whether my message was delivered when…"
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to happen?
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which part of Elephant?
+      multiple: true
+      options:
+        - Mobile app
+        - Server / API
+        - Encryption
+        - Build, CI or deployment
+        - Docs
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you've considered
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contributing
+      options:
+        - label: I'd like to work on this myself
diff --git a/.github/ISSUE_TEMPLATE/pull_request_template.md b/.github/ISSUE_TEMPLATE/pull_request_template.md
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,20 @@
+<!-- Thanks for contributing! See CONTRIBUTING.md if anything here is unclear. -->
+
+Closes #
+
+## What changed
+
+
+## How you tested it
+
+- [ ] `flutter analyze` and `flutter test` (app changes)
+- [ ] `go vet ./...` and `go test ./...` (server changes)
+- [ ] Tried it in the app (device or emulator)
+
+## Checklist
+
+- [ ] This PR adds a database migration (new `server/migrations/NNN_*_up.sql`; maintainers must apply it in production)
+- [ ] This PR changes the API, and `docs/API_CONTRACTS.md` is updated
+- [ ] UI change: screenshots are below
+
+## Screenshots
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,115 @@
+# Contributing to Elephant
+
+Thanks for your interest in Elephant! It's a small, friendly project: a Go server, a Flutter app, and the Signal Protocol in between. You don't need to know cryptography to help; most work is ordinary app and server code.
+
+Ways to help:
+
+- Fix a bug or build a feature from the [issue tracker](https://github.com/CommandLineCoding/Elephant/issues)
+- Improve the docs ([docs/](docs/), this file, the READMEs)
+- Test the app on your phone and [report bugs](https://github.com/CommandLineCoding/Elephant/issues/new/choose)
+- Share ideas in [Discussions → Ideas](https://github.com/CommandLineCoding/Elephant/discussions/categories/ideas)
+
+## Find something to work on
+
+- **New here?** Start with [`good first issue`](https://github.com/CommandLineCoding/Elephant/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). These are small and well scoped, and each one says which files to look at.
+- **Done a few PRs?** Try [`help wanted`](https://github.com/CommandLineCoding/Elephant/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) or `difficulty: medium`.
+- **Want something big?** Issues labelled `difficulty: hard` (group E2EE, multi-device, calls) are split into sub-issues. Please discuss your approach in the issue before writing code.
+- **What's next for the project:** see the [milestones](https://github.com/CommandLineCoding/Elephant/milestones).
+
+Labels tell you where the work is (`area: mobile`, `area: server`, `area: e2ee`, `area: infra`) and how big it is (`good first issue`, `difficulty: medium`, `difficulty: hard`).
+
+**Claiming an issue:** comment that you'd like to take it, and a maintainer will assign you. If there's no activity for two weeks, we may hand it to someone else. Just comment again if you're still on it. Please work on one issue at a time until your first PR is merged.
+
+## Set up
+
+You need Git, Docker (or Podman), and for the app, Flutter. The Flutter version we build with is pinned as `flutter-version` in [.github/workflows/android-release.yaml](.github/workflows/android-release.yaml).
+
+### Server
+
+```bash
+git clone https://github.com/<you>/Elephant.git
+cd Elephant
+cp .env.example .env          # the defaults work locally; Google/GitHub sign-in stays off
+docker compose up -d --build  # or: podman-compose up -d --build
+curl http://localhost:3000/api/health
+```
+
+Compose starts PostgreSQL, applies every migration, and starts the server on port 3000 (`PORT` in `.env`). To run the server outside Docker, see [Local Development](README.md#local-development).
+
+### App
+
+```bash
+cd mobile
+flutter pub get
+flutter run
+```
+
+On the sign-in screen, tap the server chip at the bottom (it says **Elephant Cloud**) and point the app at your local server:
+
+| Where the app runs | Host | Port | Use HTTPS/WSS |
+|---|---|---|---|
+| Android emulator | `10.0.2.2` | `3000` | off |
+| Phone over USB/Wi-Fi debugging | `localhost`, after `adb reverse tcp:3000 tcp:3000` | `3000` | off |
+
+Use **Test** in that sheet to check the connection. To try chats, register two accounts, for example one on an emulator and one on a phone.
+
+## Where things live
+
+| Path | What's there |
+|---|---|
+| [server/routes/](server/routes/) | Every REST route, grouped by area. A good place to start reading |
+| [server/controllers/](server/controllers/) | HTTP handlers |
+| [server/services/ws.go](server/services/ws.go) | The WebSocket hub: live delivery, typing, read receipts, presence |
+| [server/repository/](server/repository/) | SQL queries |
+| [server/migrations/](server/migrations/) | Numbered SQL migrations |
+| [mobile/lib/controllers/](mobile/lib/controllers/) | App state: auth, inbox, active chat, groups |
+| [mobile/lib/services/](mobile/lib/services/) | API client, WebSocket client, Signal Protocol, encrypted local database |
+| [mobile/lib/pages/](mobile/lib/pages/) | Screens |
+| [docs/API_CONTRACTS.md](docs/API_CONTRACTS.md) | REST, WebSocket and E2EE API reference |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the pieces fit together |
+
+## Making a change
+
+1. **Branch from `main`**, named `<issue number>-<short-description>`, e.g. `71-search-min-length`.
+2. **Keep the PR focused** on one issue. Unrelated cleanups go in their own PR.
+3. **Write commit messages** as `type(scope): summary`, e.g. `fix(server): require 2+ characters for user search`. Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`. Scopes: `server`, `mob`, `docs`, `ci`.
+4. **Run the checks** for the part you changed:
+
+   ```bash
+   # server
+   cd server
+   gofmt -l <files you changed>   # should print nothing
+   go vet ./...
+   go test ./...                  # some tests need the Compose stack running
+
+   # app
+   cd mobile
+   dart format <files you changed>
+   flutter analyze
+   flutter test
+   ```
+
+5. **Open a PR into `main`** and fill in the template. Put `Closes #<issue>` in the description. For UI changes, add screenshots.
+
+A maintainer will review it. Small follow-up commits on the same branch are fine; you don't need to squash.
+
+### Database changes
+
+- Add a **new** file named with the next number, e.g. `013_add_blocked_users_up.sql`. Never edit a migration that's already merged, because it has already run on real databases.
+- Make it safe to run twice (`IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`).
+- Tick "This PR adds a migration" in the PR template, so maintainers remember to apply it in production.
+
+### API changes
+
+- Update [docs/API_CONTRACTS.md](docs/API_CONTRACTS.md) in the same PR.
+- Keep older app versions working. F-Droid users update slowly, so add fields rather than renaming or removing them.
+
+### Encryption and security
+
+Changes under `area: e2ee` (keys, sessions, `signal_service.dart`, `/api/e2ee/*`) need a careful review, so expect more questions on those PRs. To report a vulnerability, follow [SECURITY.md](SECURITY.md) rather than opening a public issue.
+
+## Questions
+
+Ask in [Discussions → Q&A](https://github.com/CommandLineCoding/Elephant/discussions/categories/q-a), or comment on the issue you're working on. No question is too small.
+
+By contributing, you agree that your contributions are licensed under the project's [AGPL-3.0 license](LICENSE), and to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
diff --git a/README.md b/README.md
@@ -210,7 +210,7 @@ flutter analyze
 
 ```
 elephant/
-├── .github/                  # Issue templates and GitHub Actions workflows
+├── .github/                  # Issue forms, PR template and GitHub Actions workflows
 ├── docs/
 │   └── API_CONTRACTS.md      # REST, WebSocket and E2EE API reference
 ├── metadata/                 # F-Droid / store listing metadata
@@ -236,16 +236,21 @@ elephant/
 │   └── Dockerfile
 ├── compose.yaml              # PostgreSQL + migrations + server (built from source)
 ├── .env.example              # Environment variable template
+├── CONTRIBUTING.md
 ├── SECURITY.md
 ├── CODE_OF_CONDUCT.md
 └── LICENSE
 ```
 
 ## Contributing
 
-Contributions are welcome. Please open an issue using one of the [issue templates](.github/ISSUE_TEMPLATE/) before starting larger changes, and follow the [pull request template](.github/ISSUE_TEMPLATE/pull_request_template.md). Please also read the [Code of Conduct](CODE_OF_CONDUCT.md).
+Contributions are welcome, and you don't need to know cryptography to help. Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, how to claim an issue, and how to open a PR.
 
-To report a security issue, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
+- New here? Pick a [`good first issue`](https://github.com/CommandLineCoding/Elephant/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+- See what's planned in the [milestones](https://github.com/CommandLineCoding/Elephant/milestones).
+- Questions and ideas go in [Discussions](https://github.com/CommandLineCoding/Elephant/discussions).
+
+Please also read the [Code of Conduct](CODE_OF_CONDUCT.md). To report a security issue, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
 
 ## License