ci: publish a GitHub release alongside the PyPI upload, plus project docs

.github/workflows/release.yml

@@ -107,10 +107,27 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          # Full history so the generated release notes can diff against the
+          # previous tag instead of starting from an unrelated shallow root.
+          fetch-depth: 0
+
       - name: Tag the released commit
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git tag -a "v${{ needs.guard.outputs.version }}" \
             -m "Release v${{ needs.guard.outputs.version }}"
           git push origin "v${{ needs.guard.outputs.version }}"
+
+      - name: Publish the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.guard.outputs.version }}
+        run: |
+          # --generate-notes appends the commit/PR log for the range since the
+          # previous tag under this blurb.
+          gh release create "v$VERSION" \
+            --title "v$VERSION" \
+            --generate-notes \
+            --notes "Install: \`pipx install instadata==$VERSION\` · [on PyPI](https://pypi.org/project/instadata/$VERSION/)"

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for considering a contribution!
+
+## Getting started
+
+1. Fork the repo.
+2. Branch off `dev` — `main` is the branch that publishes, and it is protected.
+3. Set up a checkout:
+   ```bash
+   python -m venv .venv && . .venv/bin/activate
+   pip install -e ".[dev]"
+   ```
+4. Run `pytest` and `ruff check . && ruff format --check .` before pushing.
+5. Commit using [conventional commits](https://www.conventionalcommits.org/):
+   - `fix:` — bug fix
+   - `feat:` — new feature
+   - `docs:` — documentation
+   - `chore:` — tooling, CI, dependencies
+   - `ci:` — workflow changes
+6. Push and open a pull request against `dev`.
+
+## Code style
+
+- Python 3.13+, fully typed. New code carries annotations; the package ships
+  `py.typed` and that promise has to hold.
+- Async throughout. Nothing blocking in the request or download paths.
+- Avoid adding dependencies. The browser tier is deliberately an optional
+  extra so the common install stays small.
+- Keep the tier ladder's rules intact: `AuthenticationError` escalates a tier,
+  `RateLimitError` does not — escalating while throttled only burns the next
+  credential too.
+- Nothing is fully materialised in memory. One page at a time, whatever the
+  account size.
+
+## Tests
+
+`pytest`, with `respx` mocking HTTP. Tests must not hit the network or launch
+a browser. Add cases next to the behaviour they cover in `tests/`.
+
+## Releasing
+
+Maintainers only. Bump `version` in `pyproject.toml` and merge `dev` into
+`main`; the release workflow checks PyPI, publishes if the version is new, then
+tags the commit and opens the GitHub release. Never reuse a version number — a
+burned version on PyPI cannot be re-uploaded.
+
+## Pull request checklist
+
+- [ ] `pytest` passes
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] No new required dependencies (or a strong reason for them)
+- [ ] Commit messages follow conventional commits

README.md

@@ -35,7 +35,7 @@ Recommended, as an isolated command-line tool:
 pipx install instadata
 ```
 
-That is the whole install. `instadata` (and the short alias `bb`) land on your
+That is the whole install. `instadata` (and the short alias `idata`) land on your
 PATH in their own virtualenv, with nothing leaking into your system Python.
 
 Run it once without installing anything:
@@ -96,7 +96,7 @@ instadata highlights nasa --cookies cookies.json
 instadata whoami nasa
 ```
 
-Installed via pipx you get `instadata` and the shorter `bb`. Without a
+Installed via pipx you get `instadata` and the shorter `idata`. Without a
 console script on PATH, `python -m instadata ...` is equivalent.
 
 ### Options

SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in instadata, please report it privately.
+
+**Do not open a public GitHub issue.** Instead, send a detailed report via the **Security** tab at:
+
+https://github.com/schiz0x00/instadata/security/advisories/new
+
+You should receive a response within 48 hours. If you do not, please follow up.
+
+## Scope
+
+instadata handles session cookies, proxy credentials and untrusted responses
+from a remote service, and writes files to paths derived from that response
+data. In-scope: leaking cookies, proxy URLs or other credentials into logs,
+exception text or the `--json` report; path traversal or arbitrary writes via
+attacker-controlled usernames, shortcodes or media URLs; and code execution
+reachable from a malicious API response.
+
+Out of scope: rate limiting or blocking by Instagram, breakage caused by
+upstream API changes, and anything that requires the operator to supply a
+hostile cookie file or proxy of their own.
+
+## Supported Versions
+
+Only the latest release on PyPI receives security patches.