Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

enhancing guidelines for collaboration

Tássio Noronha82befdc10f1e
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 20e9aa83..b9414938 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -6,6 +6,8 @@ labels: enhancement
assignees: ""
---
+> Planning something large or a change to a core part of Securo? Starting here is exactly right. Opening this issue first lets us align on the idea and timing before you build, which gives your contribution the clearest path to being merged. You're also welcome to talk it through on [Discord](https://discord.gg/rUqTKtQ9S4).
+
## Problem
What problem does this feature solve? E.g. "I'm always frustrated when..."
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 1403cdc5..1b81ae31 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -13,9 +13,14 @@ Steps to verify the changes work:
1. ...
2. ...
+## Related Issue
+
+Closes #___ (or link the issue this addresses).
+
## Checklist
- [ ] Backend tests pass (`pytest`)
- [ ] Frontend lints clean (`npm run lint`)
- [ ] Frontend builds (`npm run build`)
- [ ] Translations updated (if user-facing strings changed)
+- [ ] For a large or core change, I discussed it first (issue or Discord) so we could align before the code (see [CONTRIBUTING](../CONTRIBUTING.md#before-large-or-core-changes))
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 77725e7c..6b357b62 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,6 +9,28 @@ Thanks for your interest in contributing to Securo! This guide will help you get
3. Start the stack: `docker compose up --build`
4. Open [http://localhost:3000](http://localhost:3000)
+## Where to Start
+
+New here? The smoothest first contribution is a small, self-contained one:
+
+- Browse the [open issues](https://github.com/securo-finance/securo/issues), especially those labeled `good first issue` or `help wanted`, and pick something that already has a clear scope.
+- Small bug fixes, docs improvements, and translation updates are always welcome and don't need any prior discussion, just open the PR.
+- Comment on an issue to let others know you're picking it up, so two people don't work on the same thing.
+
+Starting from an existing issue means the work is already something we want, so your PR has a clear path to being merged.
+
+## Before Large or Core Changes
+
+For anything bigger, a new feature, a refactor, or a change to a core mechanism (accounts, transactions, budgets, the rules engine, workspaces, sync, and similar), we'd love to talk it through **before** you write the code. It helps us confirm the idea fits the project's direction and that it's the right moment to build it, and it saves you from investing time in a PR that might not land.
+
+Good ways to align first:
+
+- Open a [feature request](.github/ISSUE_TEMPLATE/feature_request.md) describing what you'd like to build.
+- Comment on the related issue if one already exists.
+- Chat with us on [Discord](https://discord.gg/rUqTKtQ9S4).
+
+Once there's a shared understanding, go ahead and build. Large PRs that arrive without any prior discussion are harder to review and sometimes don't align with where the project is heading, so a quick conversation up front is the best way to make your contribution count.
+
## Development Workflow
1. Create a branch from `main`: `git checkout -b feature/your-feature`