Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
114 lines (77 loc) · 3.44 KB

CONTRIBUTING.md

File metadata and controls

114 lines (77 loc) · 3.44 KB
Raw

Contributing to XeroConnect

Thank you for your interest in contributing. XeroConnect is a small, focused library — contributions that keep the package reliable and easy to use are especially welcome.

Getting Started

Prerequisites

  • Python 3.9 or newer
  • Git

Setup

git clone https://github.com/alixaprodev/xeroconnect.git
cd xeroconnect
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Verify the install:

python -c "from xeroconnect import XeroClient, OAuthClient; print('ok')"

Running Tests

All tests use mocked HTTP requests. Do not call the live Xero API in tests.

pytest

Run a single test file:

pytest tests/test_invoices.py

Pull Requests

  1. Open an issue first for significant changes — especially new endpoints or API surface changes.
  2. Fork the repository and create a feature branch from main.
  3. Add or update tests for any behaviour you change.
  4. Keep the scope small — one logical change per pull request.
  5. Update documentation when user-facing behaviour changes (README.md, CHANGELOG.md).
  6. Ensure CI passes — pytest, python -m build, and twine check dist/*.

Commit Messages

Write clear, concise commit messages in the imperative mood:

Add contact list endpoint
Fix rate limit error message parsing
Update README OAuth example

Changelog

Add entries under [Unreleased] in CHANGELOG.md following Keep a Changelog conventions:

  • Added — new features
  • Changed — changes to existing behaviour
  • Fixed — bug fixes
  • Removed — removed features

Code Style

XeroConnect follows simple, readable Python conventions:

  • Match existing patterns — read surrounding code before adding new modules.
  • Keep modules focused — one resource per file under xeroconnect/resources/.
  • Return dicts — API methods return decoded JSON; do not add ORM models without discussion.
  • Raise typed exceptions — use the existing hierarchy in xeroconnect/exceptions.py.
  • Type hints — add annotations on public functions and methods.
  • Docstrings — brief docstrings on public classes and methods; avoid redundant comments.
  • No silent failures — API errors must raise exceptions with useful context.

Adding a New Endpoint

  1. Create or extend a resource in xeroconnect/resources/.
  2. Wire the resource in xeroconnect/client.py if it is new.
  3. Add tests in tests/test_<resource>.py using pytest-httpx.
  4. Document usage in README.md.
  5. Add a CHANGELOG.md entry.

Reporting Bugs

Use the bug report template. Include:

  • XeroConnect version
  • Python version
  • Steps to reproduce
  • Expected vs actual behaviour
  • Relevant error messages or stack traces

Do not include access tokens, client secrets, or real tenant data.

Feature Requests

Use the feature request template. Explain the business use case and which Xero API endpoint would support it.

XeroConnect intentionally covers a small subset of the Xero API. Not every endpoint belongs in this library.

Questions

Open a GitHub Discussion or an issue labelled question for general help.

License

By contributing, you agree that your contributions will be licensed under the MIT License.