Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
82 lines (62 loc) · 6.6 KB

CONTRIBUTING.md

File metadata and controls

82 lines (62 loc) · 6.6 KB
Raw

Contributing to Millennium Dawn

Thank you for your interest in contributing to Millennium Dawn! This file is a pointer to the team docs. The full guides live on the documentation site.

Quick Links

Guide What it covers
Developer Setup Guide Prerequisites, cloning, pre-commit hooks, dev tools, VSCode, day-to-day workflow. Start here.
Contributing Guide (Docs Site) Docs site setup, bun run dev, content conventions, link rules, the docs CI pipeline.
Code Stylization Guide Formatting and code structure for HOI4 script files.
Content Review Guide Quality checklist and developer expectations.
Focus Tree Design Principles Branch structure, pacing, choices.
Git Workflow Fork workflow, branch naming, commits, PRs.
AI Modding Guide Setting up local AI models for development.

One-Command Setup

python3 tools/dev_setup.py          # install hooks and Python tool dependencies
python3 tools/dev_setup.py --check  # verify environment
python3 tools/dev_setup.py --docs   # also install Node.js + Bun for docs site work

See the Developer Setup Guide for the full walkthrough.

Types of Contributions

Area Examples
Focus Trees New trees, branch reworks, prerequisite fixes
Events & Decisions Event chains, decision categories, triggered events
Ideas & National Spirits New ideas, modifier tuning, icon assignments
AI & Balance Strategy plans, equipment variants, stat tweaks
Localisation English string fixes, tooltip accuracy
Graphics Portraits, focus icons, event pictures, 3D models
Map & History State boundaries, country history, OOBs
Documentation Docs site content, guides, tutorials, dev diaries
Tooling Python scripts, CI improvements, pre-commit hooks
Bug Fixes Crash fixes, trigger errors, typos

Non-English localisation is managed through Paratranz. Do not submit translations directly.

AI Policy Summary

AI tooling is welcome. The full policy is on the Developer Setup Guide. The short version:

  • Code: AI may draft, refactor, or debug. Review all output line-by-line. Run pre-commit. Verify game objects exist. Do not submit raw AI output.
  • Localisation: AI may draft English strings. Human review required. Non-English is Paratranz-only.
    • We highly discourage pure AI generated localization and writing as it does not add anything meaningful to the description and takes away from part of the fun of modding.
  • Graphics: Pure AI-generated art is not allowed. AI-generated military vehicle side profiles are acceptable only when no existing profile is available, and must be manually finalized and reviewed.
  • Docs/PRs: AI may draft. Review for accuracy. Do not add "Generated with" footers or co-author trailers.
    • All reported issues (including those generated by AI) must follow all standards and conventions as provided by the Millennium Dawn Mod team.
  • Accountability: Any code that the AI generates, you own, so you are responsible for any issues that may arise from the utilization of this technology.

PR Expectations

  • Keep PRs focused on a single feature or fix when possible.
  • Pull Request descriptions need to be straightforward and to the point. Do not waffle about the why or how. We need to know what was broken and what the fix is.
  • Update Changelog.txt under the current top-most version heading (see Changelog Guidelines).
  • Add yourself to AUTHORS.md if this is your first contribution.
  • CI validation must pass and a team leader must approve before merge.
    • CI validation includes all validation and linters that exist within the framework under the Coding Standards and Validations.

What We Will Not Accept

  • PRs that only reformat or restructure existing code without a functional reason.
  • Machine-translated localisation (we utilize Paratranz for our translation projects.)
  • Content that violates Paradox Interactive's Terms of Service.
  • Large, unfocused PRs that touch many unrelated files. Break them up.
  • Code that is from other mods without documented consent from the other mod teams.
  • Graphics that are copyrighted without proper documented consent form their owners.

Resources

For questions, join the Discord or open an issue on our GitHub issue tracker.