You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Labels: documentation, good first issue, community Priority: P2 Blocked by: #4 (needs stable ABC), #5 (references cookiecutter)
Context
Once the plugin ABC is stable (#4) and the cookiecutter template exists (#5), a dedicated walkthrough document will close the loop for contributors who want to add a broker. The goal is: a developer with Python knowledge but no project context should be able to go from "I have XTB's export CSV" to "I have a merged PR" in under 4 hours.
Bilingual because the target audience is Polish developers, and "I speak English better than Polish for technical topics" is a valid preference both ways.
The BrokerPlugin contract — ABC reference with examples
Step-by-step: Add a new broker (with cookiecutter)
Run cookiecutter gh:pbialon/pit-38-broker-template
Inspect the generated files
Get an example export from your broker
Write the CSV parser
Run tests
Submit a PR
Common patterns — handling date parsing, currency conversion edge cases, missing columns
Testing your plugin — how to use tests/utils.py helpers (StubExchanger, buy(), sell())
Tax-correctness checklist — if your broker reports different numbers, which ones are canonical? (fee treatment, gross vs net amounts, dividend withholding)
Draft in English first, then translate. Use mermaid diagrams for the "flow of a transaction":
graph LR
A[Broker CSV] --> B[RowParser]
B --> C[Canonical CSV]
C --> D[GenericCsvLoader]
D --> E[Transaction objects]
E --> F[Tax Calculator]
Loading
Structure the "Common patterns" section around real issues hit when writing existing plugins — grep existing row_parser code for comments like # TODO, # HACK, # timezone handling, these are the learning opportunities to document.
Labels:
documentation,good first issue,communityPriority: P2
Blocked by: #4 (needs stable ABC), #5 (references cookiecutter)
Context
Once the plugin ABC is stable (#4) and the cookiecutter template exists (#5), a dedicated walkthrough document will close the loop for contributors who want to add a broker. The goal is: a developer with Python knowledge but no project context should be able to go from "I have XTB's export CSV" to "I have a merged PR" in under 4 hours.
Bilingual because the target audience is Polish developers, and "I speak English better than Polish for technical topics" is a valid preference both ways.
Acceptance Criteria
docs/DEVELOPING_PLUGINS.md(English)docs/DEVELOPING_PLUGINS.pl.md(Polish, ideally mirrored structure)cookiecutter gh:pbialon/pit-38-broker-templatetests/utils.pyhelpers (StubExchanger,buy(),sell())README.md,CONTRIBUTING.md(Create a service for business logic of stock transactions #1),pit38/plugins/README.mdTechnical Approach
Draft in English first, then translate. Use mermaid diagrams for the "flow of a transaction":
graph LR A[Broker CSV] --> B[RowParser] B --> C[Canonical CSV] C --> D[GenericCsvLoader] D --> E[Transaction objects] E --> F[Tax Calculator]Structure the "Common patterns" section around real issues hit when writing existing plugins — grep existing row_parser code for comments like
# TODO,# HACK,# timezone handling, these are the learning opportunities to document.Related
pit38/plugins/README.md(which becomes a redirect)docs/DEVELOPING_*.md(e.g. tax-rule docs)