From 1a65f06e107ee85bf7c92139bb30f3f0ffd7d8b8 Mon Sep 17 00:00:00 2001
From: przemyslawbialon <przemyslawb@monday.com>
Date: Fri, 24 Apr 2026 18:10:56 +0200
Subject: [PATCH] docs: Add bilingual issue templates and PR template (#47)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six Markdown issue templates (3 types × PL/EN) let reporters pick their
preferred language from GitHub's "New issue" dropdown. The flag emoji in
each template's `name:` makes the choice visually obvious. One shared
`config.yml` disables blank issues and points tax-rule Q&A toward
Discussions (opened in #48).

Templates mirror each other across languages and include sections
tailored to pit-38's domain:

- bug_report_{en,pl}.md — environment, sanitized CSV snippet (with PII
  warning), expected vs actual output with encouragement to cite the
  ustawa article
- feature_request_{en,pl}.md — user story in "Polish investor" form,
  motivation, scope/out-of-scope
- broker_support_{en,pl}.md — broker name/region, asset class, sanitized
  sample, operation types observed, "known quirks" (BOM, locale, sign
  position) directly informed by #33's lessons

config.yml:
- blank_issues_enabled: false → force template selection
- three contact links: Q&A in EN + PL, Broker support discussion

PULL_REQUEST_TEMPLATE.md (English, with a note inviting PL comments
because contributors are increasingly international):
- Summary + Closes #
- Tax-correctness impact (bespoke — pit-38's most important review gate)
- Testing checklist
- Documentation checklist (TAX_RULES.md, CHANGELOG, TAX_LAW_AUDIT)

Also adds the `broker-support` label so broker-request issues are
auto-tagged.

Closes #47.
---
 .github/ISSUE_TEMPLATE/broker_support_en.md  | 62 ++++++++++++++++++++
 .github/ISSUE_TEMPLATE/broker_support_pl.md  | 62 ++++++++++++++++++++
 .github/ISSUE_TEMPLATE/bug_report_en.md      | 54 +++++++++++++++++
 .github/ISSUE_TEMPLATE/bug_report_pl.md      | 55 +++++++++++++++++
 .github/ISSUE_TEMPLATE/config.yml            | 11 ++++
 .github/ISSUE_TEMPLATE/feature_request_en.md | 37 ++++++++++++
 .github/ISSUE_TEMPLATE/feature_request_pl.md | 37 ++++++++++++
 .github/PULL_REQUEST_TEMPLATE.md             | 48 +++++++++++++++
 8 files changed, 366 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/broker_support_en.md
 create mode 100644 .github/ISSUE_TEMPLATE/broker_support_pl.md
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report_en.md
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report_pl.md
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request_en.md
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request_pl.md
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md

diff --git a/.github/ISSUE_TEMPLATE/broker_support_en.md b/.github/ISSUE_TEMPLATE/broker_support_en.md
new file mode 100644
index 0000000..26ac764
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/broker_support_en.md
@@ -0,0 +1,62 @@
+---
+name: "\U0001F1EC\U0001F1E7 Broker support request"
+about: Request support for a new broker, or report a broker's CSV format change
+title: "[BROKER] "
+labels: ["broker-support", "help wanted"]
+---
+
+<!-- Use this when:
+     - Your broker isn't in the supported list and you'd like it added
+     - An existing broker changed their CSV format and pit-38 now breaks
+     For general discussion first, try Discussions → Broker support. -->
+
+## Broker
+
+- **Name**:
+- **Region** (US / EU / PL / other):
+- **Asset class** (stocks / crypto / both):
+- **Website** (helpful for sample format docs):
+
+## Sanitized export sample
+
+<!-- ⚠️ IMPORTANT: remove all PII first — account numbers, names, etc.
+     Paste 5-10 rows that cover the typical operation types your broker
+     emits. If the file is wide, a gist link is fine. -->
+
+```csv
+paste sanitized CSV here
+```
+
+## Typical columns
+
+<!-- Copy the CSV header row verbatim. This is what pit-38 needs to parse. -->
+
+## Operation types observed
+
+<!-- List the distinct values in the "Type" or "Operation" column. Examples:
+     Revolut uses "BUY - MARKET", "SELL - LIMIT", "DIVIDEND", "CUSTODY FEE",
+     "STOCK SPLIT", "CASH WITHDRAWAL", etc. -->
+
+## Known quirks
+
+<!-- Anything non-standard? Examples:
+     - Non-UTF-8 encoding or BOM
+     - European number format (1.234,56) or space as thousand separator
+     - Minus sign placement (USD -0.07 vs -USD 0.07)
+     - Localized column names (PL/DE/etc.)
+     - Multiple sheets (Excel export) -->
+
+## Tax year coverage
+
+<!-- Which tax years does your sample span? Older formats may differ. -->
+
+## Can you help implement?
+
+- [ ] I'd like to contribute the plugin myself (plugin dev docs coming — see #49, #50)
+- [ ] I can provide test data but not code
+- [ ] Just a request
+
+## Additional context
+
+<!-- Links to broker's API docs, related issues, previous GitHub projects
+     for this broker, etc. -->
diff --git a/.github/ISSUE_TEMPLATE/broker_support_pl.md b/.github/ISSUE_TEMPLATE/broker_support_pl.md
new file mode 100644
index 0000000..a112f24
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/broker_support_pl.md
@@ -0,0 +1,62 @@
+---
+name: "\U0001F1F5\U0001F1F1 Prośba o obsługę brokera"
+about: Poproś o wsparcie nowego brokera lub zgłoś zmianę formatu CSV
+title: "[BROKER] "
+labels: ["broker-support", "help wanted"]
+---
+
+<!-- Użyj tego szablonu gdy:
+     - Twój broker nie jest na liście wspieranych i chcesz żeby został dodany
+     - Obecnie wspierany broker zmienił format CSV i pit-38 przestał działać
+     Dla ogólnej dyskusji zacznij od Discussions → Broker support. -->
+
+## Broker
+
+- **Nazwa**:
+- **Region** (US / EU / PL / inny):
+- **Klasa aktywów** (akcje / krypto / oba):
+- **Strona** (pomocna dla znalezienia dokumentacji formatu):
+
+## Zanonimizowany sample eksportu
+
+<!-- ⚠️ UWAGA: najpierw usuń wszystkie dane osobowe — numery kont, nazwiska, itp.
+     Wklej 5-10 wierszy pokrywających typowe typy operacji od brokera.
+     Jeśli plik jest szeroki, link do gista jest w porządku. -->
+
+```csv
+wklej tutaj zanonimizowany CSV
+```
+
+## Typowe kolumny
+
+<!-- Skopiuj wiersz nagłówkowy CSV dosłownie. Te kolumny pit-38 musi sparsować. -->
+
+## Zaobserwowane typy operacji
+
+<!-- Wymień unikalne wartości w kolumnie "Type"/"Operation". Przykłady:
+     Revolut używa "BUY - MARKET", "SELL - LIMIT", "DIVIDEND", "CUSTODY FEE",
+     "STOCK SPLIT", "CASH WITHDRAWAL", itp. -->
+
+## Znane kwirki
+
+<!-- Coś niestandardowego? Przykłady:
+     - Kodowanie inne niż UTF-8 lub BOM
+     - Europejski format liczb (1.234,56) lub spacja jako separator tysięcy
+     - Pozycja znaku minus (USD -0.07 vs -USD 0.07)
+     - Zlokalizowane nazwy kolumn (PL/DE/itp.)
+     - Wiele arkuszy (eksport Excel) -->
+
+## Zakres lat podatkowych
+
+<!-- Jakie lata podatkowe obejmuje Twój sample? Starsze formaty mogą się różnić. -->
+
+## Czy możesz pomóc w implementacji?
+
+- [ ] Chcę napisać plugin samodzielnie (dokumentacja pluginu nadchodzi — patrz #49, #50)
+- [ ] Mogę dostarczyć dane testowe, ale nie kod
+- [ ] Tylko prośba
+
+## Dodatkowy kontekst
+
+<!-- Linki do dokumentacji API brokera, powiązanych issues, wcześniejszych
+     projektów GitHub dla tego brokera, itp. -->
diff --git a/.github/ISSUE_TEMPLATE/bug_report_en.md b/.github/ISSUE_TEMPLATE/bug_report_en.md
new file mode 100644
index 0000000..b1c187f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report_en.md
@@ -0,0 +1,54 @@
+---
+name: "\U0001F1EC\U0001F1E7 Bug report"
+about: Report incorrect tax calculations or tool crashes
+title: "[BUG] "
+labels: ["bug"]
+---
+
+<!-- Thanks for taking the time to report a bug! Please fill out the sections
+     below — incomplete reports are harder to fix. For tax-rule questions
+     (not code bugs), please use Discussions → Q&A instead. -->
+
+## Environment
+
+- **pit-38 version** (run `pip show pit-38 | grep Version`):
+- **Python version**:
+- **Operating system**:
+- **Broker(s) involved**:
+- **Tax year being calculated**:
+
+## What happened
+
+<!-- Describe the issue in 1-3 sentences. If the tax output is wrong,
+     state expected vs actual; if the tool crashed, paste the traceback. -->
+
+## Minimal CSV to reproduce
+
+<!-- ⚠️ IMPORTANT: sanitize the file first.
+     - Remove account numbers, SSN-like IDs, personal details
+     - Keep only 5-10 transactions that trigger the bug
+     - Do NOT paste full real broker exports -->
+
+```csv
+paste sanitized CSV here
+```
+
+## Expected tax output
+
+<!-- What values should appear in the CLI output? Cite the ustawa article
+     if the expected value follows from a specific rule (e.g. "art. 22 ust. 16
+     says cost carry-forward is unlimited, so I expect X PLN deductible loss
+     from 2022"). -->
+
+## Actual tax output or error
+
+<!-- Paste the full CLI output or the Python traceback. If possible, run
+     with `--log-level DEBUG` for more context. -->
+
+```
+paste output here
+```
+
+## Additional context
+
+<!-- Anything else? Related issues, what you've already tried, etc. -->
diff --git a/.github/ISSUE_TEMPLATE/bug_report_pl.md b/.github/ISSUE_TEMPLATE/bug_report_pl.md
new file mode 100644
index 0000000..f03945a
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report_pl.md
@@ -0,0 +1,55 @@
+---
+name: "\U0001F1F5\U0001F1F1 Zgłoszenie błędu"
+about: Zgłoś nieprawidłowe obliczenia podatku lub awarię narzędzia
+title: "[BŁĄD] "
+labels: ["bug"]
+---
+
+<!-- Dzięki za zgłoszenie błędu! Wypełnij poniższe sekcje — niekompletne
+     zgłoszenia są trudniejsze do naprawy. Pytania o interpretację przepisów
+     podatkowych (nie błędy w kodzie) zgłaszaj w Discussions → Q&A. -->
+
+## Środowisko
+
+- **Wersja pit-38** (uruchom `pip show pit-38 | grep Version`):
+- **Wersja Pythona**:
+- **System operacyjny**:
+- **Broker(zy)**:
+- **Rok podatkowy**:
+
+## Co się stało
+
+<!-- Opisz problem w 1-3 zdaniach. Jeśli wynik podatku jest błędny, podaj
+     oczekiwaną vs faktyczną wartość; jeśli narzędzie się wysypało, wklej
+     pełny traceback. -->
+
+## Minimalny plik CSV do odtworzenia
+
+<!-- ⚠️ UWAGA: usuń dane osobowe przed wklejeniem.
+     - Usuń numery kont, identyfikatory, inne dane osobowe
+     - Zachowaj tylko 5-10 transakcji które wywołują błąd
+     - NIE wklejaj pełnych eksportów z brokera -->
+
+```csv
+wklej tutaj zanonimizowany CSV
+```
+
+## Oczekiwany wynik podatku
+
+<!-- Jakie wartości powinny pojawić się w output CLI? Jeśli oczekiwana
+     wartość wynika z konkretnego przepisu, powołaj się na artykuł
+     ustawy (np. "art. 22 ust. 16 mówi że carry-forward kosztów krypto
+     jest bezterminowy, więc oczekuję X PLN odliczalnych strat z 2022"). -->
+
+## Faktyczny wynik lub błąd
+
+<!-- Wklej pełny output CLI lub Python traceback. Jeśli możliwe, uruchom
+     z `--log-level DEBUG` dla większego kontekstu. -->
+
+```
+wklej output tutaj
+```
+
+## Dodatkowe informacje
+
+<!-- Cokolwiek jeszcze? Powiązane issues, co już próbowałeś, itp. -->
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..6e1df5a
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Tax-rule Q&A (use Discussions)
+    url: https://github.com/pbialon/pit-38/discussions/categories/q-a
+    about: Questions about interpretation of Polish tax law belong in Discussions, not Issues. Use this if you're not reporting a code bug.
+  - name: 💬 Pytania o zasady podatkowe (Discussions)
+    url: https://github.com/pbialon/pit-38/discussions/categories/q-a
+    about: Pytania o interpretację polskiego prawa podatkowego — Discussions, nie Issues. Użyj jeśli nie zgłaszasz błędu w kodzie.
+  - name: 🏦 Broker support discussion
+    url: https://github.com/pbialon/pit-38/discussions/categories/broker-support
+    about: Informal discussion about a broker before opening a formal support request. Share sanitized CSV samples, compare workflows.
diff --git a/.github/ISSUE_TEMPLATE/feature_request_en.md b/.github/ISSUE_TEMPLATE/feature_request_en.md
new file mode 100644
index 0000000..2e40b49
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request_en.md
@@ -0,0 +1,37 @@
+---
+name: "\U0001F1EC\U0001F1E7 Feature request"
+about: Suggest an improvement or new capability
+title: "[FEATURE] "
+labels: ["enhancement"]
+---
+
+<!-- For broker support requests, please use the dedicated "🇬🇧 Broker
+     support request" template instead. -->
+
+## User story
+
+<!-- As a [type of Polish investor], I want [capability] so that [tax goal].
+     Example: "As a retail investor with a Revolut Savings account, I want
+     pit-38 to classify INTEREST operations as PIT-38-taxable income so I
+     don't have to calculate them manually." -->
+
+## Motivation
+
+<!-- What tax case or workflow does this solve? Citing the ustawa article
+     or a forum discussion helps prioritize. -->
+
+## Proposed scope
+
+<!-- What would the feature do? Minimal viable version. -->
+
+## Out of scope
+
+<!-- What is NOT included? Important to bound the ask. -->
+
+## Alternatives considered
+
+<!-- Manual workarounds you're using, similar features in other tools, etc. -->
+
+## Additional context
+
+<!-- Links to related issues, legal references, screenshots of expected UI. -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request_pl.md b/.github/ISSUE_TEMPLATE/feature_request_pl.md
new file mode 100644
index 0000000..ff94e6c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request_pl.md
@@ -0,0 +1,37 @@
+---
+name: "\U0001F1F5\U0001F1F1 Propozycja funkcji"
+about: Zasugeruj ulepszenie lub nową funkcję
+title: "[FUNKCJA] "
+labels: ["enhancement"]
+---
+
+<!-- Dla próśb o obsługę nowego brokera użyj szablonu
+     "🇵🇱 Prośba o obsługę brokera". -->
+
+## User story
+
+<!-- Jako [typ polskiego inwestora], chcę [funkcja] aby [cel podatkowy].
+     Przykład: "Jako inwestor z kontem Revolut Savings, chcę żeby pit-38
+     klasyfikował operacje INTEREST jako dochód podlegający PIT-38, żeby
+     nie liczyć ich ręcznie." -->
+
+## Motywacja
+
+<!-- Jaki problem lub workflow to rozwiązuje? Powołanie się na artykuł
+     ustawy lub wątek na forum pomaga ustalić priorytet. -->
+
+## Proponowany zakres
+
+<!-- Co ta funkcja miałaby robić? Minimalna wersja. -->
+
+## Poza zakresem
+
+<!-- Czego ta funkcja NIE obejmuje? Ważne żeby ograniczyć scope. -->
+
+## Rozważone alternatywy
+
+<!-- Obejścia których obecnie używasz, podobne funkcje w innych narzędziach. -->
+
+## Dodatkowy kontekst
+
+<!-- Linki do powiązanych issues, referencje do ustawy, screenshoty. -->
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..f9259e7
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,48 @@
+<!-- PR discussions welcome in English or Polish — whichever you're more
+     comfortable with. The template is in English as most contributors
+     are developer-focused, but reviewers will reply in your language. -->
+
+## Summary
+
+<!-- 1-3 sentences: what does this PR do, and why? -->
+
+Closes #
+
+## Changes
+
+<!-- Bullet list of notable changes. Group by module if helpful. -->
+
+-
+
+## Tax-correctness impact
+
+<!-- Does this change affect tax calculations? -->
+
+- [ ] **No impact** — purely refactor, docs, tests, CI
+- [ ] **Yes, tax output changes** — explain what and why, and whether
+      existing test expectations were updated
+
+<!-- If yes, describe the delta:
+     - Which inputs produce different output now?
+     - Is the new output correct per the ustawa? Cite article.
+     - Did you update reference fixtures / expected values? -->
+
+## Testing
+
+- [ ] `pytest tests/` passes locally
+- [ ] Added tests for new behaviour (or explained why not applicable)
+- [ ] Tested on a real CSV if tax-calc change
+
+<!-- How did you verify the change end-to-end? Manual smoke test? -->
+
+## Documentation
+
+- [ ] Updated `TAX_RULES.md` / `TAX_RULES.pl.md` if tax rules clarified or corrected
+- [ ] Updated `CHANGELOG.md` with an entry
+- [ ] Updated relevant README / plugin docs
+- [ ] Updated `TAX_LAW_AUDIT.md` if this closes an audit issue
+
+## Reviewer notes
+
+<!-- Anything the reviewer should know? Gotchas, deferred work, rationale
+     for a non-obvious choice, links to related issues / prior discussion. -->