Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (90 loc) · 4.26 KB

CONTRIBUTING.md

File metadata and controls

129 lines (90 loc) · 4.26 KB

Contributing to The Portal Realm Projects

Thank you for helping shape The Portal Realm.

This file is shared across multiple repositories under the ThePortalRealm umbrella: worldbuilding tools, TTRPG content, websites, and support libraries. Each repo may have its own README or docs with project-specific details — always read those first.

🧭 Where to Start

  • New idea, feature, or realm concept? Open an issue in the target repo and describe:

    • What you want to add or change
    • How it fits the setting, tools, or player experience
    • Any drafts, references, or sketches

  • Bug fix or small technical improvement? Check existing issues first. If nothing matches, open a new issue with:

    • Steps to reproduce
    • Expected vs actual behavior
    • Logs, screenshots, or error messages if available

  • Lore, docs, or content updates? You can usually open a PR directly. If you’re changing rules, APIs, or public-facing tools, please link or create an issue.

🧱 Types of Repositories

The Portal Realm includes several kinds of projects, such as:

  • Worldbuilding & lore – setting documents, realms, factions, timelines
  • TTRPG tools – generators, helpers, and campaign utilities
  • Websites & portals – campaign sites, reference hubs, and landing pages
  • Shared libraries & glue – code and scripts used across multiple tools

For each repo:

  • Check the README for setup or usage instructions.
  • Look for a /docs folder or wiki for deeper lore or technical notes.
  • Follow any repo-specific contribution guidelines there.

📝 How to Contribute

  1. Fork or branch from main

    • External contributors: fork the repo on GitHub.
    • Collaborators: create a feature branch from main.

  2. Create or link an issue

    • Reference an existing issue if one already tracks your change.
    • Otherwise, open a new issue and outline:
      • What you’re changing
      • Why it’s needed
      • Any impact on tools, lore, or other realms

  3. Keep canon and style in mind

    • For lore/content: match the tone, themes, and constraints of the setting.
    • For tools: respect existing data formats, APIs, and user-facing behavior.

  4. Make focused, readable commits

    • Group related changes together.
    • Use clear messages that explain why as well as what.
    • If the repo uses commit tags (e.g. [skip ci], [publish], [publish-zip]), follow any conventions noted in the README.

  5. Add tests or validation where appropriate

    • For code: add or update unit/integration tests if present.
    • For generators or tools: consider sample inputs/outputs or fixtures.
    • For content: ensure links, references, and cross-doc navigation are correct.

  6. Open a Pull Request

    • Clearly describe the change and link the related issue.
    • Mention if your change affects:
      • CI / GitHub Actions
      • Shared libraries or templates
      • Multiple repos, tools, or lore collections

  7. Respond to review

    • Keep feedback constructive and focused on the work.
    • It’s fine to push follow-up commits — just keep them tidy and readable.

⚖️ Code of Conduct

All contributions must follow the The Portal Realm Code of Conduct.

We expect respect, patience, and collaboration — whether you’re editing a small utility script or adding a whole new corner of the realm.

🔒 Security & Vulnerabilities

If you discover a security issue in a ThePortalRealm project:

Please include:

  • A clear description of the problem
  • Steps or scripts to reproduce
  • Any potential impact (users, sites, tools, or data)

We’ll coordinate fixes here and in any related repositories.

💡 Need Help?

If you’re unsure about:

  • Which repo is the right place for your change
  • How a tool, generator, or site is supposed to behave
  • What impact your update might have on other realms, tools, or lore

Open a “Question” issue in the relevant repo with as much context as you can.

The Portal Realm is meant to be a shared world, not a locked vault — it’s always okay to ask before you step through a new gate.