Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
104 lines (65 loc) · 5 KB

CONTRIBUTING.md

File metadata and controls

104 lines (65 loc) · 5 KB
Raw

Contributing to Modtale

First off, thank you for considering contributing to Modtale! We are a community-driven platform building the future of Hytale content sharing. Whether you're fixing a bug, improving documentation, or proposing a new feature, your help is appreciated.

1. Getting Started

Prerequisites

  • Node.js: v22.12.0+
  • Java JDK: 21 (Amazon Corretto or OpenJDK)
  • MongoDB: Local instance or Atlas
  • Warden (Mock Mode): Since our security scanner is closed-source, external contributors must set WARDEN_ENABLED=false in their backend configuration to run the API locally.

Installation

Please refer to the "Local Development" section in the README.md for detailed setup instructions.

2. Mock Database & PR Previews

Modtale provides a public mock MongoDB dataset for local testing and PR review. The mock DB is generated by a trusted GitHub Actions workflow instead of being committed as static JSON files.

The generated artifact may include real public project fields that are already available from the public API, such as author names, project descriptions, categories, public media URLs, public release metadata, and a safe public-comment subset. It must not include real draft, pending, private, or unlisted projects, emails, passwords, tokens, scan results, reports, admin enforcement actions, admin logs, private notifications, or detailed analytics. Those private/admin-only areas are generated synthetically.

The mock DB refresh workflow runs automatically only when a trusted push to main or develop changes backend model or repository code. Each successful refresh deletes older modtale-mock-db-json artifacts before uploading the new one so GitHub Actions storage does not fill up with stale downloads.

Import the Mock DB Locally

  1. Download the latest modtale-mock-db-json artifact from the Refresh Mock Database GitHub Actions workflow.
  2. Extract the artifact into mock-db/collections/.
  3. Install MongoDB Database Tools so mongoimport is available.
  4. Import it:
MONGODB_URI=mongodb://localhost:27017 \
MONGODB_DATABASE_NAME=modtale-mock \
bash mock-db/import.sh

Point the backend at that database:

export MONGODB_URI=mongodb://localhost:27017
export MONGODB_DATABASE_NAME=modtale-mock
export WARDEN_ENABLED=false

Mock sign-in accounts use the password password. See mock-db/README.md for the current account list and seeding modes.

PR Preview Deployments

Every pull request to develop gets a Cloud Run preview backed by a preview-only Mongo database seeded from the sanitized mock template database. PR previews run untrusted PR code against preview-only infrastructure with no production/dev secrets, no real object-storage credentials, no OAuth credentials, no Warden credentials, and no production domains.

Preview services are named per PR and are deleted when the PR closes. The preview workflow must keep using the trusted base branch workflow/build config for deployment orchestration; PR code can affect the application being built, but it must not receive GitHub or production cloud credentials.

The preview project must use dedicated no-production-access service accounts for both Cloud Build (GCP_PREVIEW_BUILD_SERVICE_ACCOUNT) and Cloud Run (GCP_PREVIEW_RUNTIME_SERVICE_ACCOUNT). The preview Mongo secret must point only at a preview/mock Mongo environment, never dev or prod.

3. Git Workflow & Branching

We use a feature-branch workflow rooted in develop.

For External Contributors

  1. Fork the Repo: You cannot create branches directly on the main Modtale repository. Please fork the project to your own account.
  2. Branch off develop: Create your feature branch from develop in your fork.
git checkout develop
git pull origin develop
git checkout -b feat/my-cool-feature
  1. Submit PR: Open a Pull Request from your fork's branch to Modtale's develop branch.

4. Coding Standards

Backend (Java/Spring Boot)

  • Style: We follow Google Java Format.
  • Linting: Please ensure your code is formatted before submitting. Most IDEs (IntelliJ, VS Code) have plugins for Google Java Format.
  • Architecture: Follow the existing patterns:
  • Controllers handle web concerns.
  • Services handle business logic.
  • Repositories handle data access.
  • Do not leak implementation details (like specific Mongo queries) into Controllers.

Frontend (React/Astro)

  • Style: While we don't strictly enforce a linter config yet, please try to match the existing code style.
  • Components: Prefer functional components with hooks.
  • State: Use React Context for global state only when necessary.

5. Licensing & Legal

By contributing to Modtale, you agree that:

  • License: Your code will be licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Questions? Join our Discord Server to chat with the dev team and other contributors.