Contribute To HackVillage

1. Ways To Contribute

You don't need to write code to make a real difference:

• Report bugs: found something broken? Open a detailed issue.
• Suggest features: have an idea that fits the roadmap? Start with an issue.
• Write code: fix a bug, build a roadmap feature, or make something faster.
• Improve the docs: the README, this guide, or code comments that explain why something works the way it does.
• Review the escrow contract: the PrizeVault contract is public. Read it, flag concerns, and open an issue with your findings.
• Design and UX: propose improvements in an issue with mockups or wireframes attached.
• Testing: add coverage, especially for edge cases in escrow and payouts.

2. Before You Start

By taking part you agree to our Code of Conduct. For anything bigger than a small fix, open an issue first and agree on the approach before writing code. It saves everyone time.

3. Reporting Bugs

Search the existing issues first, then open a bug report with:

• Numbered steps to reproduce it.
• What you expected to happen, and what actually happened (with any error message).
• Your OS, Node.js version, and browser. Never paste real secrets.
• How serious it is: does it block escrow, payouts, or judging, or is it cosmetic?

For escrow or payout bugs, include the payment reference or transaction hash if you have one.

4. Suggesting Features

Open a feature request describing the problem it solves, your proposed solution, the alternatives you ruled out, and how it fits the roadmap. Large changes, such as new escrow flows or payment rails, need rough agreement in the issue before any code is written.

5. Development Setup

You'll need:

• Node.js 22.13 or newer (CI runs Node 24).
• pnpm, the only package manager the project uses. The version is pinned in package.json, so run corepack enable to get the right one.
• PostgreSQL 15 or newer, running locally.
• Git.

# Fork on GitHub, then clone your fork
git clone https://github.com/<your-username>/HackVillage.git
cd HackVillage
git remote add upstream https://github.com/CodeWithEugene/HackVillage.git

pnpm install
cp .env.example .env      # then fill in your values

pnpm run db:migrate       # create the database tables
pnpm run db:seed          # optional: realistic Nairobi demo data
pnpm dev                  # http://localhost:3000

To get started you only need DATABASE_URL, DIRECT_URL, NEXTAUTH_SECRET, NEXTAUTH_URL, and NEXT_PUBLIC_APP_URL. Everything else in .env.example is optional:

• Without Paystack keys, deposits and payouts run in simulation mode, so you can test the whole escrow flow without real money.
• Without an RPC URL and contract address, blockchain records are simulated too.
• Without a Brevo key, emails are printed to the console instead of sent.
• Google and GitHub sign in only appear once their client IDs are set.

Two helpers speed up local work: pnpm run dev:fund -- <slug> funds a pending hackathon through the real escrow path, and pnpm run dev:cycle -- <slug> runs the full judging, winners, and payout cycle.

6. Project Structure

• app/: Next.js App Router pages and layouts.
• components/: shared React components (UI primitives and patterns).
• lib/: auth, database, queue, environment, and the ports that talk to Paystack, the blockchain, email, and storage.
• services/: escrow, payouts, judging, media, legacy check ins, and Proof of Work profiles.
• contracts/: the PrizeVault and PrizeVaultFactory Solidity contracts.
• db/: the Prisma schema, migrations, and seed data.
• tests/: unit tests and integration tests that run against a real PostgreSQL database.

7. Branches And Commit Messages

main is production and is protected, so every change lands through a pull request. Branch from main with a clear name, such as feature/team-invites or fix/payout-retry, and open your pull request against main.

Commit messages follow Conventional Commits, and CI checks every one:

<type>(<scope>): <short summary>

feat(escrow): lock the prize pool when a hackathon is published
fix(payout): prevent a duplicate payout on retry

• Types: feat, fix, docs, style, refactor, test, chore, perf, ci.
• Scopes: escrow, payout, profiles, events, auth, db, contracts, ui, api, docs, ci.
• Breaking changes include BREAKING CHANGE: in the commit footer.

8. Pull Requests

• Keep each pull request to one feature or fix.
• Fill in the pull request template: a summary, why the change is needed, and how you tested it.
• Link the issue it resolves with Closes #123.
• Wait for CI to pass: linting, type checks, unit and integration tests against PostgreSQL, smart contract tests, and a production build.
• Ask a maintainer to review, and never merge your own pull request.
• Never include secrets, credentials, or .env files.

9. Code Style

• TypeScript everywhere in app/, components/, lib/, and services/, in strict mode.
• No any. When a type is truly unknown, use unknown and narrow it.
• Prefer named exports and React Server Components. Only reach for client components when you need interactivity, and never fetch data in them.
• Wrap every call to Paystack or the blockchain in error handling, and keep each service function to a single job.
• Before committing, run pnpm run lint, pnpm run typecheck, and pnpm run format.

10. Testing

pnpm test                  # everything
pnpm run test:unit         # pure logic only
pnpm run test:integration  # against your local PostgreSQL
pnpm run contracts:test    # Hardhat tests for the contracts

• New code comes with tests. Escrow and payout code needs strong coverage.
• Money paths are tested against a real database, never mocks. Failure and rollback paths must be covered.
• Tests never make live calls to Paystack or a public blockchain.

11. Working With The Escrow Layer

services/escrow/, services/payout/, and contracts/ handle real prize money, so they carry extra rules:

• Open an issue first for any change here, even one that looks like a small fix, and wait for a maintainer to agree on the approach.
• Never remove or weaken rollback logic. If a payment or network call fails, the money stays locked in the vault. No partial or ambiguous states.
• Every payout must be idempotent. A retry must never pay anyone twice.
• Contract changes need a testnet deployment (Polygon Amoy) and an updated ABI in the pull request.
• Two maintainer approvals are needed to merge anything in these folders.

Read How Escrow Works for the full picture of how the money moves.

12. Reporting Security Issues

Please don't report security vulnerabilities in public issues. Use GitHub's private vulnerability reporting (preferred), or email cyberuhurultd@gmail.com with the subject [SECURITY] HackVillage. We acknowledge reports within 72 hours and triage them within 7 days. See the security policy for details.

13. License

HackVillage is licensed under the Apache License 2.0. By contributing, you agree that your contributions are licensed under the same terms, and you keep the copyright to your own work.

14. Get Started

Browse the open issues, star the repository, or email us at info@hackvillage.xyz if you aren't sure where to begin.