diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..dc02f80 --- /dev/null +++ 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 deleted file mode 100644 index dde9251..0000000 --- a/.github/ISSUE_TEMPLATE/but_report.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: Bug Report -about: Create a report to help us improve -title: '[BUG]: ' -labels: bug -assignees: '' ---- - -## Description -A clear and concise description of what the bug is. - -## To Reproduce -Steps to reproduce the behavior: - -## Expected Behavior -What should happen? - -## Environment -- Device: [e.g. Pixel 7] -- OS: [e.g. Android 14] -- App Version: [e.g. v0.1.5] \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index f84af30..503798b 100644 --- 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. \ No newline at end of file + 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 deleted file mode 100644 index 9abb8a0..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: Feature Request -about: Suggest an idea for this project -title: '[FEAT]: ' -labels: enhancement -assignees: '' ---- - -## Description -A clear and concise description of what the feature is. - -## Use Case -Why is this important for the Elephant ecosystem? - -## Proposed Implementation -How do you envision this being integrated? \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..992f827 --- /dev/null +++ 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 deleted file mode 100644 index ccb6916..0000000 --- a/.github/ISSUE_TEMPLATE/pull_request_template.md +++ /dev/null @@ -1,15 +0,0 @@ -## Summary -Describe the changes in this PR. - -## Type of Change -- [ ] Bug fix -- [ ] New feature -- [ ] Refactoring -- [ ] Documentation update - -## Testing Performed -- [ ] Verified on emulator/physical device. -- [ ] Code passes lint checks. - -## Screenshots (if applicable) -[Paste screenshots here] \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..0296601 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,20 @@ + + +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 new file mode 100644 index 0000000..d2d2dfb --- /dev/null +++ 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//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 `-`, 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 # should print nothing + go vet ./... + go test ./... # some tests need the Compose stack running + + # app + cd mobile + dart format + flutter analyze + flutter test + ``` + +5. **Open a PR into `main`** and fill in the template. Put `Closes #` 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 index 0ebe770..9fd20e5 100644 --- 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,6 +236,7 @@ elephant/ │ └── Dockerfile ├── compose.yaml # PostgreSQL + migrations + server (built from source) ├── .env.example # Environment variable template +├── CONTRIBUTING.md ├── SECURITY.md ├── CODE_OF_CONDUCT.md └── LICENSE @@ -243,9 +244,13 @@ elephant/ ## 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