3b9d759b4b
- Clone of github.com/fluxerapp/fluxer (official upstream) - SELF_HOSTING.md: full VM rebuild procedure, architecture overview, service reference, step-by-step setup, troubleshooting, seattle reference - dev/.env.example: all env vars with secrets redacted and generation instructions - dev/livekit.yaml: LiveKit config template with placeholder keys - fluxer-seattle/: existing seattle deployment setup scripts
149 lines
6.1 KiB
Markdown
149 lines
6.1 KiB
Markdown
# Contributing to Fluxer
|
||
|
||
Thanks for contributing. This document explains how we work so your changes can land smoothly and nobody wastes time on work we can't merge.
|
||
|
||
## Quick rules (please read)
|
||
|
||
### 1) All PRs must target `canary`
|
||
|
||
`canary` is our trunk branch. Open all pull requests against `canary`. PRs targeting other branches will be closed or retargeted.
|
||
|
||
### 2) All PRs must include a short description
|
||
|
||
Every PR must include a short description covering:
|
||
|
||
- what changed
|
||
- why it changed
|
||
- anything reviewers should pay attention to
|
||
|
||
A few bullets is fine.
|
||
|
||
### 3) Open an issue before submitting a PR
|
||
|
||
We strongly prefer that every PR addresses an existing issue. If one doesn't exist yet, open one describing the problem or improvement and your proposed approach. This gives maintainers a chance to weigh in on direction before you invest time, and avoids the mutual displeasure of:
|
||
|
||
- you doing significant work, and
|
||
- us having to reject or postpone the change because it doesn't align with current goals, or because we aren't ready to maintain what it introduces
|
||
|
||
For small, obvious fixes (typos, broken links, trivial one-liners) you can skip the issue and go straight to a PR.
|
||
|
||
Ways to coordinate on larger work:
|
||
|
||
- open an issue describing the problem and your proposed approach
|
||
- open a draft PR early to confirm direction
|
||
- discuss with a maintainer in any channel you already share
|
||
|
||
If you're unsure whether something needs an issue first, it probably does.
|
||
|
||
### 4) Understand the code you submit
|
||
|
||
You should understand every change in your PR well enough to explain and defend it during review. You don’t need to write an essay, but you should be able to give a brief summary of what the patch does and why it’s correct. You may not use AI to generate a bug report, pull request description, or GitHub comment in any form, except for a 1:1 translation if English isn't your native language.
|
||
|
||
The maintainer [uses LLMs in a limited capacity](https://blog.fluxer.app/how-i-built-fluxer-a-discord-like-chat-app/#:~:text=The%20LLMephant%20in%20the%20room). That’s how he was able to build the final version of Fluxer largely on his own over five years, with help from a supportive group of early testers. Without limited, controlled LLM use, he likely would have needed more starting capital to achieve the same result and hire a team of engineers.
|
||
|
||
If you use LLMs, use them responsibly. They can be helpful for rubber-ducking and for scaffolding boilerplate from thorough specifications, detailed guidance, and test coverage that verifies behaviour rather than implementation. This kind of platform cannot be built via autonomous code generation. Please disclose any LLM usage in your contribution.
|
||
|
||
We also ask contributors to treat each other with respect on this topic. People hold a wide range of views on LLMs, often rooted in ethical conviction. A contribution that is reviewable, understandable, and properly tested should be evaluated on its merits.
|
||
|
||
## Workflow
|
||
|
||
1. Fork the repo (or create a branch if you have access).
|
||
2. Create a feature branch from `canary`.
|
||
3. Make changes.
|
||
4. Open a PR into `canary` with a short description.
|
||
5. Address review feedback and CI results.
|
||
6. We squash-merge approved PRs into `canary`.
|
||
|
||
We strongly prefer small, focused PRs that are easy to review.
|
||
|
||
### Commit style and history
|
||
|
||
We squash-merge PRs, so the PR title becomes the single commit message on `canary`. For that reason:
|
||
|
||
- PR titles must follow Conventional Commits.
|
||
- Individual commits inside the PR don't need to follow Conventional Commits.
|
||
|
||
If you like to commit in small increments, feel free. If you prefer a tidier PR history, force-pushes are welcome (for example, to squash or reorder commits before review). Just avoid rewriting history in a way that makes it hard for reviewers to follow along.
|
||
|
||
## Conventional Commits (required for PR titles)
|
||
|
||
Because the PR title becomes the squash commit message, we require Conventional Commits for PR titles.
|
||
|
||
We prefer type/subject to be mostly lowercase.
|
||
|
||
Format:
|
||
|
||
- `type(scope optional): short description`
|
||
|
||
Examples:
|
||
|
||
- `fix: handle empty response from api`
|
||
- `feat(auth): add passkey login`
|
||
- `docs: clarify canary workflow`
|
||
- `refactor: simplify retry logic`
|
||
- `chore(ci): speed up checks`
|
||
|
||
Breaking changes:
|
||
|
||
- `feat!: remove legacy auth endpoints`
|
||
- `refactor(api)!: change pagination shape`
|
||
|
||
Common types:
|
||
`feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert`
|
||
|
||
## Tests (guidance)
|
||
|
||
We care about confidence more than ceremony. Add tests when they provide real value.
|
||
|
||
### Backend changes
|
||
|
||
For backend changes, add a unit test.
|
||
|
||
- If a unit test would require heavy mocking to be meaningful, restructure the code so it can be tested cleanly through its interfaces.
|
||
- If you're unsure how to approach this, discuss it with a maintainer before investing time.
|
||
|
||
### Frontend changes
|
||
|
||
We don't generally encourage new unit tests for frontend code unless:
|
||
|
||
- the area already has unit tests, or
|
||
- the change is complex or sensitive, and a unit test clearly reduces risk
|
||
|
||
In most cases, clear PR notes and practical verification are more valuable.
|
||
|
||
## Formatting and linting
|
||
|
||
Don't block on formatting or linting before opening a PR. CI enforces required checks and will tell you what needs fixing before merge.
|
||
|
||
Open the PR when it's ready for review, then iterate based on CI and feedback.
|
||
|
||
## PR checklist
|
||
|
||
Before requesting review:
|
||
|
||
- [ ] PR targets `canary`
|
||
- [ ] PR title follows Conventional Commits (mostly lowercase)
|
||
- [ ] PR includes a short description of what/why
|
||
- [ ] You understand every change in the PR and can explain it during review
|
||
- [ ] Tests added or updated where it makes sense (especially backend changes)
|
||
- [ ] CI is green (or you're actively addressing failures)
|
||
|
||
Optional but helpful:
|
||
|
||
- screenshots or a short recording for UI changes
|
||
- manual verification steps
|
||
|
||
## Code of Conduct
|
||
|
||
This project follows a Code of Conduct. By participating, you're expected to uphold it:
|
||
|
||
- See [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
|
||
|
||
## Security
|
||
|
||
Please don't report security issues via public GitHub issues.
|
||
|
||
Use our security policy and reporting instructions here:
|
||
|
||
- https://fluxer.app/security
|