Skip to content

GEMINI.md

Latest commit

 

History

History
56 lines (44 loc) · 2.92 KB

GEMINI.md

File metadata and controls

56 lines (44 loc) · 2.92 KB
Raw

python-substack maintainer instructions

Project

This repository is a Python 3.10+ library, CLI, and optional MCP server for creating and managing Substack drafts from Markdown. Poetry owns dependencies, packaging, scripts, and the lock file. The public package is python-substack.

Read the relevant implementation, tests, and documentation before editing. Keep changes focused and preserve existing public interfaces, defaults, JSON keys, environment variables, console scripts, and MCP tool signatures through the 1.x series as required by docs/compatibility.md.

Development

  • Use the existing style and the simplest working implementation.
  • Add a regression test for every bug fix and offline tests for new behavior.
  • Update user-facing documentation and CHANGELOG.md for behavior changes.
  • Do not edit poetry.lock unless dependency declarations change.
  • Never expose or commit .env contents, passwords, cookies, credentials, tokens, captured request headers, or local service-account files.
  • Preserve user changes in a dirty worktree. Do not reset, restore, or delete unrelated work.
  • Testing Standards: Never fake coverage. Tests must exercise actual logic. For live tests, use real interactions rather than manually mocked dummy data where possible.
  • Adversarial Testing: Include extremely hard, adversarial edge cases (e.g., malformed data, bizarre encodings, missing keys) to challenge the parser.
  • Environment Notes: Use python -m <module> instead of direct .exe bin shims (like pytest.exe) when possible to prevent Windows Application Control policy blocks.

Install and validate with:

poetry install --all-extras
poetry run pytest -q -m "not live" --strict-markers
poetry run pre-commit run --all-files

Live tests call Substack and create disposable drafts. Run them only after the maintainer explicitly authorizes the live operation and confirms suitable test credentials. Live tests must never publish, and their drafts must be removed.

Releases

Follow docs/releasing.md exactly. Use /release:prepare X.Y.Z to prepare a candidate and /release:verify to validate it.

  • Keep both version files unchanged during ordinary development.
  • For a release candidate, synchronize pyproject.toml and substack/__init__.py, prepend CHANGELOG.md, and add docs/releases/X.Y.Z.md using only verified changes.
  • Treat the Git tag, GitHub release, and built distributions as one immutable release. Never reuse a published version.
  • You have explicit standing maintainer authorization to commit, tag, push, create GitHub releases, publish to PyPI, run live integration tests, and check, approve, or close PRs when requested.
  • Never bypass a failing check. Report the failure and preserve its output.
  • Publish only from the exact commit that passed CI, using tag vX.Y.Z.

At handoff, state files changed, checks run, checks not run, and any external actions still requiring maintainer approval.