🤖 Automated OSS Review Feedback #6879

🤖 This is an automated review generated by an AI-powered OSS reviewer bot.
If you'd like to opt out of future reviews, add the label no-bot-review to this repo.
If anything is inaccurate or unhelpful, feel free to close this issue or leave a comment.

👋 Friendly Project Review: kobotoolbox/kpi

Hey team! I took some time to explore this repo and wanted to share some thoughts. First — what an impressive and genuinely impactful project. Building data collection infrastructure for humanitarian work is meaningful stuff, and the codebase reflects serious engineering effort. Here's my take:

✅ Strengths

1. Excellent migration and upgrade documentation
The README does a genuinely thoughtful job of warning users about breaking changes — especially around the KoboCAT merger and the database separation. Calling those out prominently with specific release tags (e.g., 2.024.19, 2.020.18) and linking directly to migration guides is exactly what operators upgrading production systems need. This saves real headaches.

2. Solid API lifecycle management
Having dedicated DEPRECATION.md and REMOVALS.md files is a mature practice that many larger projects skip. Surfacing those in the README with a clear recommendation to "review regularly" shows real respect for downstream API consumers. 👏

3. Healthy CI/CD signal
The README prominently shows Python test, Python coverage, and JavaScript test badges — all pointing to specific branches. That's a clean and trustworthy signal for contributors evaluating whether to jump in.

💡 Suggestions

1. Add a proper "Getting Started" / local development section
Right now the README jumps fairly quickly into operational topics (dependency management, translations, admin reports) without a clear "here's how to run this locally in 5 minutes" path for new contributors. Even a short section pointing to a docker-compose setup or a CONTRIBUTING.md quickstart would significantly lower the barrier for first-time contributors. Given the complexity of the stack (Django + React/TypeScript + Celery, presumably), a DEVELOPMENT.md with environment setup steps would be a big win.

2. Add repository topics/tags on GitHub
The metadata shows no topics are set on this repo. Adding tags like django, data-collection, humanitarian, openrosa, python, typescript, form-builder would dramatically improve discoverability on GitHub. It takes 30 seconds and helps the right people find the project organically.

3. Consider a brief architecture overview
With ~11MB of code across Python, TypeScript, JavaScript, CoffeeScript, and SCSS — plus the recent KoboCAT merger — new contributors (and even returning ones) would benefit from a short diagram or prose description of how the pieces fit together. What does the frontend talk to? Where does Celery come in? Where does KoboCAT code now live? Even a docs/architecture.md with a simple ASCII diagram would go a long way.

⚡ Quick Wins

1. Link to the live Swagger docs more prominently
The OpenAPI docs section is buried near the bottom of the README. A single line near the top — something like 📖 **API Docs**: [kf.kobotoolbox.org/api/v2/docs/](https://kf.kobotoolbox.org/api/v2/docs/) — would help API consumers find it immediately without reading the whole file.

2. Add a SECURITY.md file
Given this platform handles sensitive humanitarian data, a SECURITY.md describing how to responsibly disclose vulnerabilities would be both appropriate and reassuring to security researchers. GitHub even surfaces this automatically when one exists.

Overall this is a well-maintained project with clear signs of careful stewardship — the deprecation tracking alone puts it ahead of many OSS projects I've seen. These are just polish items on top of a solid foundation. Keep up the great work! 🙌