Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
94 lines (67 loc) · 3.08 KB

CONTRIBUTING.md

File metadata and controls

94 lines (67 loc) · 3.08 KB
Raw

Contributing

Thanks for helping improve Nadia. Nadia is a Mix library for the Telegram Bot API and Telegraph API, so changes should stay small, well-tested, and aligned with the public APIs those services document.

Supported Toolchain

Nadia requires Elixir 1.20 or later and Erlang/OTP 27 or later. CI currently checks Elixir 1.20.1 on OTP 27.3 and OTP 29.0.

Install dependencies before running checks:

mix deps.get

Local Checks

For ordinary changes, run the checks that match the files you touched. Before a pull request is ready, run the full offline set:

mix format --check-formatted
mix compile --warnings-as-errors
mix test
mix docs --warnings-as-errors
git diff --check

The normal test suite is offline and does not need Telegram credentials.

Live Telegram Tests

Optional maintainer smoke tests live under test/live and are tagged :telegram_live:

mix test --only telegram_live

These tests are default-off. They require credentials from .env.live.local, seeded from .env.live.local.example, and two bots with Bot-to-Bot Communication Mode enabled.

Public API And Changelog

Update CHANGELOG.md for user-facing changes. This includes public API changes, configuration changes, dependency or transport changes, behavior changes, new Mix tasks, guides, and notable workflow changes. Internal-only refactors usually do not need a changelog entry.

Keep README and ExDoc guides current when changing installation, configuration, public wrappers, runtime helpers, or release behavior. Generated ExDoc output goes to doc/ and should not be committed.

Bot API Maintenance

When adding or changing Telegram Bot API wrappers, verify method names, parameters, and response shapes against the current official Telegram documentation. Preserve backwards-compatible Elixir function names where practical, and add tests for wrapper request encoding and response parsing.

Telegram and Telegraph response parsing should not create atoms from remote JSON keys. Unknown future fields should remain ignored until Nadia explicitly models them.

Req is Nadia's production HTTP transport. Do not reintroduce HTTPoison, hackney, ExVCR, VCR cassettes, or hackney-specific proxy configuration.

Working In The Repository

The worktree may contain other people's unfinished work. Do not revert unrelated changes. Keep commits focused, and avoid broad refactors unless they are needed for the change being made.

Release Process

Publishing is done by GitHub Actions, not by local mix hex.publish. The release workflow is .github/workflows/release.yml; it verifies the tag version against mix.exs, runs release checks, builds the Hex package, and publishes to Hex after the hex-publish environment is approved.

Before tagging a release, confirm mix.exs, CHANGELOG.md, README install snippets, ExDoc guides, and packaged files match the intended version. Release tags should be annotated tags such as:

git tag -a v1.6.0 <release-commit> -m "Release 1.6.0"
git push origin v1.6.0

Do not run mix hex.publish locally unless the maintainer explicitly decides to bypass CI.