From 714210ee383d3d26b04014926c1023f76193faab Mon Sep 17 00:00:00 2001 From: Oussema Frikha Date: Mon, 22 Jun 2026 23:42:54 +0100 Subject: [PATCH] chore: add CONTRIBUTING.md, SECURITY.md, and PR template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three standard OSS files to harden the project surface as the SDK starts getting real downloads: CONTRIBUTING.md Setup (pip install -e .[dev]), how to run lint/types/tests, optional smoke test against a real token, branch / commit / PR conventions, bug-reporting checklist, release process. Calls out what's in scope (bug fixes, doc improvements, new endpoint wrappers) vs not (adding a brand-new social platform — backend work first). SECURITY.md GitHub uses this to populate the repo's Security tab. Documents supported versions (0.1.x only), how to report vulnerabilities (support@socialapis.io, not a public issue), our SLA (ack in 72h, initial assessment in 7 days), and what's out of scope (rate limits, public-by-design data exposure, etc.). .github/PULL_REQUEST_TEMPLATE.md Pre-fills new PR descriptions with a Summary / Test plan / Checklist structure. Asks contributors to confirm ruff + mypy + pytest pass, smoke test re-run for typed-model methods, CHANGELOG updated. Lightweight, no enforcement. None of these change any code, tests, or behaviour — purely documentation + governance scaffolding. Ruff and the test suite are unaffected. --- .github/PULL_REQUEST_TEMPLATE.md | 28 +++++++++ CONTRIBUTING.md | 99 ++++++++++++++++++++++++++++++++ SECURITY.md | 48 ++++++++++++++++ 3 files changed, 175 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8283bf2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,28 @@ +## Summary + + + +## Test plan + + + +- [ ] `ruff check .` +- [ ] `ruff format --check .` +- [ ] `mypy socialapis tests` +- [ ] `pytest` + +For changes touching `get_page_info`, `get_profile_details`, or +`get_group_details`, also re-run the smoke test: + +- [ ] `python scripts/integration_smoke.py` (requires `SOCIALAPIS_TOKEN`) + +## Checklist + +- [ ] `CHANGELOG.md` updated under `## [Unreleased]` for any user-visible change +- [ ] Public method signatures unchanged (or a clear reason if changed) +- [ ] If a Pydantic model field was added/removed, real-API behaviour verified diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2308958 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Contributing to socialapis + +Thanks for the interest. This SDK ships the Python client for the +[socialapis.io](https://socialapis.io) REST API — most contributions are +small bug fixes, doc improvements, or new endpoint method wrappers when +the backend adds a new route. + +## What kinds of contributions are welcome + +- Bug fixes (anything that produces wrong / surprising output) +- New endpoint method wrappers when the API adds an endpoint +- Pydantic model improvements (correcting field names, adding missing + fields, tightening types) +- Test coverage improvements +- Documentation: typos, clearer examples, fixing stale field references +- Performance improvements that don't change behaviour + +## What's NOT a fit + +- **Adding a new social platform.** The SDK can only wrap endpoints that + exist on the backend. New platforms (TikTok / X / LinkedIn / YouTube) + need backend work first; once they're live, we add the methods here. +- **Breaking changes to public method signatures** without a strong + reason. We try hard to keep `from socialapis import Facebook` stable. +- **Removing the migration aliases** (`FacebookScraper`, + `InstagramScraper`). They're part of the public contract for users + migrating from kevinzg/arc298. + +## Setup + +```bash +git clone https://github.com/SocialAPIsHub/socialapis-python.git +cd socialapis-python +python -m venv .venv && source .venv/bin/activate +pip install -e ".[dev]" +``` + +Requires Python 3.10+. + +## Verify your change + +Run these locally before opening a PR — CI will reject anything that +fails them: + +```bash +ruff check . # lint +ruff format --check . # formatting +mypy socialapis tests # type check (--strict) +pytest # tests + coverage gate (70% minimum) +``` + +`ruff check --fix .` and `ruff format .` will auto-fix most lint/format +issues. + +## Optional: integration smoke test + +For changes that touch the typed-model methods (`get_page_info`, +`get_profile_details`, `get_group_details`), re-run the smoke script +against a real API token to confirm Pydantic field names still match the +live API: + +```bash +export SOCIALAPIS_TOKEN="" +python scripts/integration_smoke.py +``` + +The script never prints the token. Cost: ~13 credits out of your 200/month +free tier. + +## PR conventions + +- **Branch off `main`** with a prefixed name: `fix/`, `feat/`, `docs/`, + `chore/`, `refactor/` +- **Commit subject**: short imperative ("fix: …"), no trailing period +- **Squash-merge** is the merge style (keeps `main` history linear and + readable). The squash commit's subject becomes the entry on `main`. +- **CHANGELOG.md** — update under `## [Unreleased]` for any user-visible + change (new method, removed field, behaviour change) +- **CI must be green** before merge — lint, types, tests on Python + 3.10 / 3.11 / 3.12 / 3.13 + +## Reporting bugs + +Open an issue with: + +- Python version + SDK version (`python -c "from socialapis import __version__; print(__version__)"`) +- Minimal reproduction (~20 lines if possible) +- What you expected vs. what happened +- The `request_id` from the response if the SDK raised an `APIError` + (it's on every typed exception — `exc.request_id`) + +Security issues: please don't open a public issue. See +[`SECURITY.md`](SECURITY.md) for the disclosure flow. + +## Releases + +Releases are cut from `main` on a `vX.Y.Z` tag push. The release workflow +publishes to PyPI via Trusted Publishing — no manual API tokens involved. +The CHANGELOG section becomes the GitHub Release notes. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..7ccd52b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,48 @@ +# Security Policy + +## Supported versions + +We patch security issues on the **latest minor release line** only. + +| Version | Supported | +|---|---| +| 0.1.x | ✅ | +| < 0.1 | ❌ | + +If you're on an older version, update to the latest `socialapis-sdk` and +re-test before reporting — the issue may already be fixed. + +## Reporting a vulnerability + +**Please do not open a public GitHub issue for security vulnerabilities.** +Public issues are indexed instantly and attackers watch for them. + +Instead, email **support@socialapis.io** with: + +- A description of the issue +- Steps to reproduce (or a minimal proof of concept) +- The version(s) affected +- Your assessment of the impact (which endpoints / users are at risk) + +If the issue affects the hosted API at `api.socialapis.io` (rather than +this Python SDK specifically), the same address routes correctly — we'll +triage it on our backend. + +## What we promise + +- **Acknowledgement within 72 hours** that we've received the report +- **Initial assessment within 7 days** — whether we've reproduced it and + what severity we're treating it as +- **A patched release** as soon as a fix is ready, typically within a + week for critical issues +- **Credit in the CHANGELOG** if you'd like (let us know) + +## Out of scope + +These aren't security issues for this SDK: + +- API rate limits / quota enforcement — those are billing / API behaviour +- Wrong / outdated data returned by the API — that's a backend issue +- Username enumeration via public endpoints — Instagram / Facebook + already expose that publicly; the SDK just reflects it +- Anything requiring physical access to a machine running the SDK