How I Vet an Open-Source Dependency Before Betting On It

Description and use

Six practical checks revealed documentation and feature gaps in an open‑source engine, enabling a revised integration plan without abandoning the project.

Problem

How do I know an open-source project does what its documentation claims before I build on it?

Outcome

The six checks corrected all three faulty assumptions in the spec within ten minutes of curl and grep, allowing the project to stay viable with adjusted requirements (no OIDC, manual payouts, pinned commit).

Workflow

• 1. Query GitHub API for repo vital signs (created_at, pushed_at, stargazers_count, etc.)
• 2. Grep README, ARCHITECTURE.md, and docs for authentication protocols (oidc|sso|saml)
• 3. Inspect the target branch line in feature docs to confirm shipping status
• 4. Compare the engine’s data model for commission rules against the spec’s required shapes
• 5. Review the paid tier table to determine feature gating (SSO, API tokens, etc.)
• 6. Verify payout model compatibility with local payment regulations (Stripe Connect vs manual)
• 7. Plan fallback solutions (e.g., reverse proxy for SSO) before implementation

Evidence

Ten minutes of curl and grep later, two of those were false and the third was half‑true.

Source

Zero hits. The app authenticates with its own magic‑link sessions and per‑persona API keys; it does not speak OIDC at all.

Source

Target branch: multi‑tenant. The doc is a design for a branch that is not the default branch — it describes work in flight, so the feature is not in the code you would install.

Source

The payout model was stripe_connect | manual, and self‑hosted mode was documented as "operator manages out‑of‑band" — i.e. you move the money yourself.

Source