✏️ Edit Page

Documentation Directory

Contributing Guide

How to submit new games, author developer profiles, and propose metadata corrections.

Contributing Guide

Thank you for helping make HELIX Gaming DB the most accurate, comprehensive, and dependable gaming metadata repository!

We actively encourage submissions for indie games, Patreon creations, itch.io visual novels, and emulated classics.

📋 Contribution Rules & Quality Invariants

  1. Working Image URLs Only: Never submit placeholder images or temporary links. Capsule covers, hero wallpapers, and screenshots must be hosted on permanent, reliable CDNs (such as Steam Akamai CDN, itch.zone, or official publisher domains).
  2. No AI Hallucinations: All synopses, release dates, and developer lists must be verified from primary sources (storefront receipt, developer Patreon/blog, official website, or game files).
  3. Disambiguation & Aliases: Always include common abbreviations, romanizations, and search aliases (e.g. FFXIV, FF14 for FINAL FANTASY XIV).
  4. Developer Registration: Every game must be linked to a registered developer profile in api/v1/developers/. If the developer is not yet registered, add their profile in the same Pull Request.
  5. Schema Validation: All submissions must pass npm run test:schema with 0 errors before submitting a PR.

💡 Ways to Contribute

There are two primary ways to contribute metadata to HELIX Gaming DB:

  1. GitHub Issues (No Code Required): Use our structured issue forms to submit game metadata, report corrections, or register new studios.
  2. Direct Pull Requests: Fork the repository, create JSON files in api/v1/, run local validation, and open a PR.

🛠️ Step-by-Step Developer Submission Process

1. Fork & Branch

git clone https://github.com/YOUR-USERNAME/helix-gaming-db.git
cd helix-gaming-db
git checkout -b add/my-awesome-game

2. Copy Starter Templates

Instead of authoring JSON from scratch, copy the pre-built templates provided in the repository:

# For a new game
cp api/v2/contribute/templates/game.json api/v1/games/my-awesome-game.json

# For a new developer studio
cp api/v2/contribute/templates/developer.json api/v1/developers/my-studio.json

(Templates are also accessible via REST API at /api/v2/contribute/templates/game.json and developer.json)

3. Edit Metadata & Verify Invariants

  • Set slug to match the exact filename (excluding .json).
  • Ensure all developers in developers: [...] exist in api/v1/developers/.
  • Ensure all images load over HTTPS from official high-speed CDNs.
  • If the game contains 18+ content, set "ageRating": "Adults Only 18+" and include "Adult" in genres or tags.

4. Build Indexes & Validate

# Rebuild search indexes, manifests, and v1/v2/v3 tiers
npm run build:index

# Validate all files against Draft 2020-12 JSON schemas
npm test

5. Open Pull Request

Push your branch to your GitHub fork and submit a Pull Request against main. Our automated GitHub Actions workflow will validate all schemas and indexes automatically. Our PR template will help you summarize your changes.