Skip to content

docs: Write DEVELOPING_PLUGINS.md (EN + PL) #55

@przemyslawbialon

Description

@przemyslawbialon

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.

Acceptance Criteria

  • docs/DEVELOPING_PLUGINS.md (English)
  • docs/DEVELOPING_PLUGINS.pl.md (Polish, ideally mirrored structure)
  • Covers these sections:
    1. What is a broker plugin? — one paragraph overview
    2. The BrokerPlugin contract — ABC reference with examples
    3. 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
    4. Common patterns — handling date parsing, currency conversion edge cases, missing columns
    5. Testing your plugin — how to use tests/utils.py helpers (StubExchanger, buy(), sell())
    6. Tax-correctness checklist — if your broker reports different numbers, which ones are canonical? (fee treatment, gross vs net amounts, dividend withholding)
    7. Getting help — link to Discussions (Add a port for revolut as a data source  #3)
  • Includes at least 2 worked code examples (Revolut and Binance) showing the "before cookiecutter scaffolding → after full plugin" diff
  • Linked from README.md, CONTRIBUTING.md (Create a service for business logic of stock transactions  #1), pit38/plugins/README.md

Technical 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]
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.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    communityCommunity building and contributiondocumentationImprovements or additions to documentationgood first issueGood for newcomers

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions