Contributing to Flux
Flux is in early development; v0.2 is the current version (release notes). The application is a TypeScript monorepo run with Docker Compose (see the README and architecture). Its UI follows one design, the final design “Prostota”. Contributions to usability, accessibility, documentation, and reproducible bug fixes are welcome.
Choose the right place
Section titled “Choose the right place”- Use Issues for reproducible bugs and concrete feature proposals. Search existing issues first.
- Use Discussions for questions, open-ended ideas, and substantial product or architecture changes.
- Follow SECURITY.md to report vulnerabilities privately.
- Looking for a first task? Open issues labelled good first issue are small, name the files to change and say how to check the result; help wanted marks larger work. Comment on the issue that you are taking it before you start, so that two people do not do the same task.
English is preferred for shared documentation and discussions. Polish reports and questions are welcome. Be respectful, give constructive feedback, and avoid posting personal or confidential information.
Before starting a large change, describe the problem, proposed scope, and expected user benefit in an issue or discussion. Wait for maintainer feedback so the work fits the direction of the project. Small, clearly scoped fixes can go straight to a pull request.
Follow work on the project board
Section titled “Follow work on the project board”The Flux board tracks repository issues. The cards are the same issues you see in the repository, so descriptions, assignees, labels, and conversations stay together.
GitHub Projects uses these built-in automations:
| Event | Issue status on the board |
|---|---|
| A new open issue is added automatically | Todo |
| A pull request is linked to resolve the issue | In Progress |
The issue is closed, including by merging its resolving PR into main |
Done |
Todo includes incoming reports and proposals; maintainers still decide which work to accept and prioritize. Done reflects a closed issue, so check its closure reason to distinguish completed work from declined proposals or duplicates.
When a PR will resolve an issue, put a closing reference in the PR description:
Closes #123Replace 123 with the actual issue number and target the main branch. GitHub
links the PR to the issue and closes the issue when that PR is merged into
main. For related work that does not resolve an issue, use Refs #123; that
reference does not trigger the same closing workflow.
Open a draft PR while implementing the change, then mark it ready for review when it is ready for a maintainer. Both draft and ready PRs keep the linked issue In Progress. The card’s linked PR shows the PR state; review does not have a separate board column. Closing a PR without merging it does not complete the issue.
Make a change
Section titled “Make a change”You need Git, Docker Engine 25 or newer (or Docker Desktop) with Compose, and Python 3 for the repository checks. You do not need Node.js or PostgreSQL on your computer.
-
Fork ColdPhase/flux to your GitHub account.
-
Clone your fork and create a branch from the latest
main:Terminal window git clone https://github.com/YOUR-USERNAME/flux.gitcd fluxgit remote add upstream https://github.com/ColdPhase/flux.gitgit fetch upstreamgit switch -c fix/short-description upstream/main -
Start the application with
./flux up(or./flux devfor hot reload) and, for sample data with two logins,./flux demo, as described in the application foundation guide. A documentation-only change does not need the application running. -
Make a focused change. Put code in the layer that owns it (architecture) and tests under
app/tests/app. A UI change matches the final design: its tokens, components, screens and rules. -
Run the checks below, commit your changes, and push your branch to your fork.
-
Open a PR against
ColdPhase/flux:mainand complete the PR template. Use a draft PR if the change is still being developed.
You do not need to join the ColdPhase organization or receive write access to contribute through a fork.
Verify your change
Section titled “Verify your change”Choose checks for the changed behavior and its dependencies using the verification policy. Targeted checks are valid both during iteration and before review; full suites are needed for broad impact and integrated release acceptance. Required PR CI still builds, type checks, lints and runs portable tests.
The complete Docker commands build and check the application against disposable stacks. Use them when the selected verification needs the full coverage:
./scripts/check_application.sh./scripts/check_ui.shEach script builds the application image before it runs a test, so expect minutes, not seconds: on a busy
shared host (2026-10-30) one browser module took 16 minutes, one API test file 9 and the unit-test image 3, while
the tests themselves ran in under 30 seconds each; a warm Docker build cache shortens the builds.
Each script uses its own Compose project; set FLUX_TEST_PORT/FLUX_TEST_MAILPIT_PORT
or FLUX_UI_PORT/FLUX_UI_MAILPIT_PORT when the default ports are taken. Follow
the shared-host limits.
Architecture § Tests says which check runs which tests
and where a new test goes.
Select relevant existing tests as well as new regression cases. For example:
# One browser module, or Module.Class.test, from app/tests/ui./scripts/check_ui.sh test_docs
# One core test file (app/tests/app/*-core.test.ts); these need no databasedocker build --file docker/Dockerfile --target test --tag flux-unit appdocker run --rm --network none flux-unit node_modules/.bin/tsx --test tests/app/push-core.test.tsdocker image rm flux-unitAPI test files need the database and the API. Name them to run only those on the
Docker stack (paths as seen from app/); the browser, restart and
unavailable-configuration checks are skipped in this form:
./scripts/check_application.sh tests/app/search.test.tsUse the full ./scripts/check_application.sh for broad impact.
Repository and documentation checks:
python3 scripts/check_agent_setup.pypython3 -m unittest discover -s tests -p 'test_*.py'git diff --checkGitHub Actions runs the repository checks and a fast application check (build, type check, lint, architecture and core tests) on pull requests; it does not run the Docker suites above, so mention which ones you ran. For UI changes, also verify the behavior in a browser and describe your checks:
- Reproduce the issue before the fix and check the same steps afterward.
- Check the browser console for new errors.
- For UI changes, check keyboard use and both a wide and a narrow window, in light and dark. Compare each screen with the matching final design render. Put the screenshots in the PR, or in a CI workflow artifact linked from it, instead of committing them (evidence size).
- For changes to saved data, use disposable sample data and check export and reload behavior. Nothing is kept compatible before the first public release (architecture), so change the current shape in place.
- For documentation changes, check that links, file names, and commands match the repository.
The ./flux demo data gives a realistic company with a space to check against. Mention the browser, operating system, and manual checks you used. If
you could not verify relevant behavior, state that in the PR.
Review and project decisions
Section titled “Review and project decisions”The current maintainers are @PelikanFix16 and @Zamojski5. Maintainers set project direction, review proposals, and decide which changes to merge.
Changes to main go through pull requests. A maintainer other than the PR author
must approve the change and review conversations must be resolved. New commits
may require another review. Approved changes are merged
with squash merging.
Response goal: a maintainer gives a first answer to an issue or PR from an outside contributor within 2 working days. The answer can be a review, a question, or a decision about the direction. If you have heard nothing after that, mention a maintainer in a comment.
Please keep each PR focused on one problem. Updating documentation alongside a behavior change helps other contributors understand and maintain it. If people or operators will notice the change, add one changelog file under changes/ with your PR number (not a line in CHANGELOG.md). GOVERNANCE.md explains who decides what and how to become a maintainer.
Working with coding agents
Section titled “Working with coding agents”Codex and Claude share AGENTS.md and the skills in
.agents/skills/. The agent collaboration guide describes
task contracts, conversations through issues/PRs, independent evaluation, and
how each maintainer runs one /goal agent session. Its
CI and release process also assigns agents
responsibility for validation and packaging once the stack is chosen.
Use the implementation-task issue form for planned work. Ordinary contributions remain welcome through the existing issue and PR process; the autonomous release protocol applies when a task is admitted to that workflow.