docs: Add CONTRIBUTING.md and Contributor Covenant CoC (#46)

.gitignore

@@ -7,4 +7,7 @@ resources/*
 .venv/
 *.egg-info/
 dist/
-build/
+build/
+.coverage
+htmlcov/
+.pytest_cache/

CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer at **przemyslawb@monday.com**, or privately via GitHub's [report abuse flow](https://github.com/pbialon/pit-38/security/advisories/new) if you prefer a channel tied to the repository.
+
+All complaints will be reviewed and investigated promptly and fairly. The maintainer is obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,246 @@
+# Contributing to pit-38
+
+Thanks for your interest. `pit-38` is an open-source tax calculator people
+rely on to file real PIT-38 declarations, so correctness matters more than
+speed. Friendly code review is how we get there — first-time contributors
+are very welcome.
+
+Discussions and PR reviews happen in **English or Polish** — use whichever
+you're more comfortable with. The code and docs are primarily English so
+that international contributors can participate, but tax rules are Polish
+and forum links are usually Polish, so both languages coexist here
+naturally.
+
+> **[🇵🇱 Wersja polska niedługo](https://github.com/pbialon/pit-38/issues)** —
+> jeśli wolisz pisać po polsku, śmiało otwieraj issue / PR po polsku.
+> Odpiszemy w Twoim języku.
+
+---
+
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Development setup](#development-setup)
+- [Running tests](#running-tests)
+- [Linting and style](#linting-and-style)
+- [Submitting a pull request](#submitting-a-pull-request)
+- [Adding a new broker plugin](#adding-a-new-broker-plugin)
+- [Reporting tax-law bugs](#reporting-tax-law-bugs)
+- [Code of Conduct](#code-of-conduct)
+- [Where to ask questions](#where-to-ask-questions)
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/pbialon/pit-38
+cd pit-38
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/
+```
+
+If that passes, you have a working dev environment. Skip to
+[Submitting a pull request](#submitting-a-pull-request) if you already know
+what you want to change, or read on for details.
+
+## Prerequisites
+
+- **Python 3.10+** — the code uses `X | Y` union syntax and other 3.10
+  features. Earlier versions won't work.
+- **git** — for cloning and branching.
+- **pipx** (optional) — only needed if you want to install `pit-38` as a
+  CLI tool; not required for development.
+
+## Development setup
+
+Use a virtualenv so the editable install and its dev dependencies don't
+pollute your system Python:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The `[dev]` extra installs `pytest`, `flake8`, and `coverage` (see
+`pyproject.toml`). After install, `pit38` is available on your `PATH` and
+points at the checkout, so your edits are picked up without reinstalling.
+
+Sanity check:
+
+```bash
+pit38 --help
+```
+
+## Running tests
+
+The full suite runs in seconds:
+
+```bash
+pytest tests/
+```
+
+End-to-end tests, which exercise the CLI against real anonymized CSV
+fixtures, live under `tests/e2e/`:
+
+```bash
+pytest tests/e2e/
+```
+
+With coverage:
+
+```bash
+pytest tests/ --cov=pit38 --cov-branch
+```
+
+**Test conventions** (worth matching when you add tests):
+
+- Tests use `unittest.TestCase` — not pytest fixtures.
+- Helpers live in `tests/utils.py` — factory functions like `buy()`,
+  `sell()`, `apple()`, `usd()`, `zl()`, and `StubExchanger` (fixed 4.0
+  USD→PLN). Prefer these over hand-rolled objects.
+- If you change tax-calculation behaviour, update or add an E2E fixture
+  that shows the change end-to-end.
+
+## Linting and style
+
+Flake8 runs in CI with a minimal config — only syntax errors and
+undefined names fail the build (E9, F63, F7, F82). We deliberately keep
+the bar low here so style nitpicks don't stall contributions. Run it
+locally if you want:
+
+```bash
+flake8 pit38/ tests/ --select=E9,F63,F7,F82
+```
+
+General code style:
+
+- Follow patterns already present in the module you're editing. When in
+  doubt, mirror the neighbouring file.
+- No new abstractions unless the task requires them. Three similar lines
+  beat a premature helper.
+- Type hints are encouraged on public functions but not required.
+
+## Submitting a pull request
+
+1. **Fork and branch.** Branch names roughly follow the pattern
+   `<type>/<issue-number>-<short-slug>`:
+   - `fix/33-revolut-csv-bom`
+   - `feat/9-csv-loader-consolidation`
+   - `docs/46-contributing`
+   - `refactor/...`, `test/...`, `chore/...`
+
+2. **Commit style.** Terse, imperative mood, present tense. First line
+   under ~72 chars. Include the issue number when closing one:
+   ```
+   fix: Revolut CSV with BOM, lowercase headers, and unknown operations (#33)
+   ```
+   Longer rationale goes in the body. Look at `git log` for tone.
+
+3. **Link to the issue.** In the PR body, put `Closes #<n>` so the issue
+   auto-closes on merge. If there's no issue yet and the change is
+   non-trivial, open one first — reviewers like having the "why"
+   captured somewhere durable.
+
+4. **Use the PR template.** `.github/PULL_REQUEST_TEMPLATE.md` asks
+   specifically about tax-correctness impact. Fill it in honestly — even
+   "purely refactor, no tax impact" is a valid answer and saves reviewer
+   time.
+
+5. **Keep PRs focused.** One issue per PR, ideally. If you find
+   tangential bugs while working, file them as separate issues rather
+   than bundling.
+
+6. **Expect review.** For anything that touches tax output, expect a
+   careful pass. Reviewers may ask for references to the *ustawa*
+   article (the Polish income tax act) or ask you to add a regression
+   fixture.
+
+## Adding a new broker plugin
+
+Broker plugins live under `pit38/plugins/` and transform a broker-specific
+CSV export into the standardized format that `pit38` consumes. Each
+plugin is self-contained. See
+[`pit38/plugins/README.md`](pit38/plugins/README.md) for the plugin
+architecture overview (PL/EN).
+
+**Reference implementations** (read these first):
+
+- **Stocks** — `pit38/plugins/stock/revolut/` (most complete, handles
+  BOM, unknown operations, dividends, fees, stock splits)
+- **Crypto** — `pit38/plugins/crypto/binance/`
+
+**High-level recipe:**
+
+1. Create `pit38/plugins/stock/<broker>/` (or `crypto/<broker>/`).
+2. Implement an entry point (`__main__.py` or a CLI command) that
+   accepts `--input-path` and `--output-path`.
+3. Parse the broker's export, emit rows in the standardized CSV shape
+   (see `pit38/data_sources/stock_loader/example_format.csv` or
+   `pit38/data_sources/crypto_loader/example_format.csv`).
+4. Share number/currency parsing via
+   `pit38.plugins.normalization` (`normalize_currency_layout`,
+   `parse_amount`) rather than re-rolling regex. Revolut and E*Trade
+   both use it — new plugins should too.
+5. Add the broker to the `pit38 import` subcommand group in
+   `pit38/cli.py`.
+6. Write unit tests for the row parser and at least one E2E test with
+   an **anonymized** sample CSV under `tests/e2e/fixtures/`. Remove
+   account numbers, names, and PII before committing.
+7. Update the "Supported Brokers" table in both `README.md` and
+   `README.pl.md`.
+
+If you're unsure whether a format quirk belongs in shared normalization
+or plugin-local code, open a draft PR — easier to discuss over real code
+than in the abstract.
+
+**Before you start coding**, please open a broker-support issue using
+the [broker support template](.github/ISSUE_TEMPLATE/broker_support_en.md)
+and attach a sanitized CSV sample. This lets us confirm we have
+reference data to validate against, and flags any format ambiguities
+before you invest time.
+
+## Reporting tax-law bugs
+
+Bad tax math = wrong PIT filings, so tax-correctness bugs get special
+treatment. If you suspect `pit38` produces the wrong number:
+
+1. **Open an issue immediately** — don't wait until you have a fix.
+   Other users may be affected.
+2. **Include a minimal reproducible CSV** (anonymized — remove PII
+   before pasting). Five rows is usually enough.
+3. **Cite the tax rule.** If you can, point to the article of the
+   ustawa (*Ustawa o podatku dochodowym od osób fizycznych*) or to
+   [docs/TAX_RULES.md](docs/TAX_RULES.md) section that you believe is
+   being violated. A KIS interpretation or forum link works too.
+4. **State expected vs actual output.** "Expected tax of 123.45 PLN
+   because X, got 678.90 PLN." Numbers matter here.
+5. **Label it `tax-correctness`.** Maintainers will prioritize these
+   above feature work.
+
+If you fix a tax-law bug yourself, update `docs/TAX_RULES.md` /
+`docs/TAX_RULES.pl.md` if the rule itself was under-documented, and
+add a regression test with the reproducing fixture so it can't silently
+come back.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](CODE_OF_CONDUCT.md).
+By participating, you agree to abide by its terms. Issues relating to
+conduct can be raised privately via a GitHub issue marked confidential
+or by emailing the maintainer listed in `CODE_OF_CONDUCT.md`.
+
+## Where to ask questions
+
+- **[GitHub Discussions](https://github.com/pbialon/pit-38/discussions)**
+  — tax-rule Q&A, broker format questions, general discussion. English
+  and Polish both welcome.
+- **[Issues](https://github.com/pbialon/pit-38/issues)** — bug reports,
+  feature requests, broker-support requests. Templates exist for each.
+- **PR comments** — implementation-level questions during review.
+
+Happy hacking, and thanks for helping make Polish tax filing less
+painful.

README.md

@@ -84,7 +84,11 @@ For a detailed description of the rules, see:
 3. **Calculate** — stock profits use the FIFO method; crypto uses yearly cost/income aggregation
 4. **Tax** — 19% flat tax rate is applied, with automatic deduction of losses from previous years
 
-## Development
+## Contributing
+
+Contributions are welcome — including first-time open-source PRs and new broker plugins. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup, test conventions, PR guidelines, and a walkthrough for adding a new broker plugin.
+
+Quick dev setup:
 
 ```bash
 python3 -m venv .venv
@@ -93,6 +97,8 @@ pip install -e ".[dev]"
 pytest tests/
 ```
 
+This project follows the [Contributor Covenant v2.1](CODE_OF_CONDUCT.md).
+
 ## Disclaimer
 
 This tool is provided for **informational purposes only** and does not constitute tax advice. Always verify your calculations with a qualified tax advisor before filing your PIT-38 declaration.

README.pl.md

@@ -84,7 +84,11 @@ Szczegółowy opis zasad:
 3. **Kalkulacja** — zyski z akcji obliczane metodą FIFO; kryptowaluty wg rocznej sumy kosztów i przychodów
 4. **Podatek** — stawka 19% z automatycznym odliczeniem strat z lat poprzednich
 
-## Rozwój projektu
+## Współtworzenie
+
+Zapraszamy do kontrybucji — również osoby, dla których to pierwsza przygoda z open source, oraz chętnych do dodania wsparcia nowego brokera. Pełny przewodnik znajdziesz w **[CONTRIBUTING.md](CONTRIBUTING.md)** (konfiguracja środowiska, testy, wytyczne do PR i instrukcja dodawania pluginu brokera). Issues i PR-y po polsku są mile widziane.
+
+Szybka konfiguracja środowiska:
 
 ```bash
 python3 -m venv .venv
@@ -93,6 +97,8 @@ pip install -e ".[dev]"
 pytest tests/
 ```
 
+Projekt przestrzega [Contributor Covenant v2.1](CODE_OF_CONDUCT.md).
+
 ## Zastrzeżenie
 
 To narzędzie służy wyłącznie **celom informacyjnym** i nie stanowi porady podatkowej. Przed złożeniem deklaracji PIT-38 zweryfikuj obliczenia z doradcą podatkowym.