Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
305 lines (215 loc) · 14.1 KB

CONTRIBUTING.md

File metadata and controls

305 lines (215 loc) · 14.1 KB
Raw

Contributing to ed4e

Nice! You want to be a part of the ed4e system for Foundry VTT. We're happy to see contributions.

All types of contributions are valued. Please make sure to check the following:

  • read this guide ;)

It will make things for us maintainers much easier, and the process faster and smoother for all.

If you like to contribute but can't do it in code or don't have the time, there are other ways to help:

  • Report bugs
  • Write or improve documentation
  • Share it with others, e.g. on social media
  • Tell us your feedback
  • Star the project
  • ... and more!

Table of Contents

How can I Contribute?

🐛 Report Bugs

Before reporting a bug, please make sure to check existing issues to see if it has already been reported. If you find it, feel free to add additional information in the comments.

When you create a new bug issue, include as many details as possible.

Please use our templates.

✨ Suggest Features

Suggest some cool new stuff! As with bug reports (and issues in general), please check existing issues first to avoid duplicates.

Please use our templates.

📝 Improving Documentation

For many people, this is the biggest chore. At the same time, it is one of the most valuable things to have. Your contributions can include:

  • Fixing typos
  • Adding examples
  • Clarifying confusing sections
  • Translating documentation
  • ... and more!

🔧 Contribute Code and Content

You can code or create content like art, sound, or other assets? Awesome! Make sure of the following:

  • there always is an open issue for whatever it is you are contributing
  • if there is no open issue for your contribution, please open one first to discuss the change
  • make sure your issue is not a duplicate of an existing one

For more info, have a look at Development.

Disclaimer for generative AI

Creativity is made by people, for people.

We don't know if generative AI is here to stay, but acknowledge that it's becoming more and more used.

No AI is used for the generation of any kind of assets, texts, and other creative media. All sources must be indicated accordingly.

People might use it to support the development process. If you do so, please make sure to:

  • review and test everything thoroughly
  • never blindly copy-paste code or content generated by AI tools
    • => everything must be checked and understood
    • => no vibe coding!
  • make sure you have the rights to use and distribute any content generated by AI tools
  • clearly state in your contribution which parts were generated by AI tools, if applicable

We strive to keep generative AI to a minimum.

Development

Getting started

  1. Clone the repository and place it in Data/systems/ed4e of your Foundry VTT user data directory.
  2. If you haven't already, install Node.js.
  3. Install dependencies by running npm install in the project root.

Common Commands

Command Description
npm install Install project dependencies
node <yourFoundryInstallation>main.js --dataPath=<yourFoundryDataPath> Start Foundry VTT from the command line
node gulp.js --color --gulpfile <yourSystemDirectory>/gulpfile.mjs default Start watching LESS files and auto-compile to CSS
node gulp.js --color --gulpfile <yourSystemDirectory>/gulpfile.mjs buildCSS Build CSS once
node gulp.js --color --gulpfile <yourSystemDirectory>/gulpfile.mjs lint Run the ESLint
node gulp.js --color --gulpfile <yourSystemDirectory>/gulpfile.mjs buildAll Build all artifacts for release (currently only CSS)
node tools/pullJSONtoLDB.mjs Create compendia entries from JSON data files (make sure the working directory is set to the project root
node tools/pushLDBtoJSON.mjs Export compendia entries to JSON data files (make sure the working directory is set to the project root

Workflow

Branching model

  • main is the trunk and always represents the next release
  • No direct pushes to main
  • Work happens in branches
  • Branches are rebased on main before first push
  • Branches are deleted after merge
  • Conventional Branch for branch names:
    • main for the main branch
    • feature/ticket-number-clear-concise-description for new features
    • bugfix/ticket-number-clear-concise-description for bug fixes
    • hotfix/ticket-number-clear-concise-description for urgent fixes
    • release/x.y.z for release branches
    • chore/ticket-number-clear-concise-description for non-code tasks like dependency, docs updates, etc.

Feature branches

  • Work locally as long as possible
  • Clean up commits before pushing
  • Add changes to CHANGELOG.md
  • Open PRs only when the feature is coherent and builds

Pull Requests

  • Keep it small and focused
  • PRs are merged using merge commits
  • At least one approval is required
  • Add a gitmoji at the beginning of your PR title
  • Each commit should be meaningful and buildable
  • CI must pass before merge

Coding

Try to follow existing code style and patterns as best you can. Always clean up lint before submitting:

  • npm run lint to check code
  • npm run lint:fix to fix issues automatically

Dependencies should be kept to a minimum. If you want to add a new dependency, please discuss it in the related issue first.

Testing

The project has Vitest set up as a framework for unit testing as well as the Foundry module Quench. Since this is still a hobbyist project, there are few tests written yet. We do want to change this to reach a point where the automation supplies good enough information for the development process.

Unit Tests

If possible, try to include unit tests for all production code that you write. The test code follows a mirrored structure of the production code in the "tests" directory. All unit tests must be successful when merging into main.

Quench Test Reports

Quench tests run inside Foundry VTT (in the browser), so they cannot be executed on CI directly. Instead, you have to run them locally and commit the resulting report before opening a PR.

How to generate a report
  1. Launch Foundry with the ED4E system and the Quench module enabled.
  2. Open a world that loads the system in development mode.
  3. Open the Quench UI and click Run to execute all test batches.
  4. When the run finishes, you are asked if you wish to download the report, named latest.json.
  5. Move the downloaded file to tests/quench/reports/latest.json, overwriting the previous one.
  6. Commit the updated file together with your changes.
CI behavior

The Quench Report workflow runs on every pull request and relies on the report generated above. It fails if any test is failed or errored, or if the file is missing / empty.

It currently relies on trust that the report is fresh enough and generated by you on your pull request.

Commit Messages

Conventional Commits style for commit messages. They are enforced through commitlint, with the following type prefixes:

  • build: for build related changes or external dependencies (example scopes: gulp, npm)
  • chore: for maintenance tasks
  • ci: for CI/CD related changes (example scopes: github-actions, workflows, husky)
  • docs: for documentation changes
  • feat: for new features
  • fix: for bug fixes
  • perf: for performance improvements
  • refactor: for code changes that neither fix a bug nor add a feature
  • revert: for reverting previous commits
  • style: for code style changes
  • test: for adding or updating tests

For more information you can have a look at the Angular convention.

The usual best practice should be followed, like using the imperative mood, keeping messages concise yet descriptive, and providing additional context in the body if necessary.

Internationalization (i18n) and Localization (l10n)

You can help making the system approachable to a broader audience by adding localizations in a language you are proficient in. To do so, you still need to set up a development environment and make pull requests, since the localization files are part of the code.

Setup and Workflow

Foundry VTT has its own i18n framework. Please have a look at the Foundry Knowledge Base for localization or the Foundry VTT wiki entry for localization.

If the language you are providing localization for has no JSON file yet, you can create a new one in the lang directory if you feel comfortable with that. Otherwise, feel free to get in touch with the maintainers of the GitHub repo. They can set it up for you accordingly.

There are different plugins for IDEs or even entire software to support the i18n process. Some examples are:

Committing lang files

⚠️ Important: We use pre-commit git hooks that work on lang files. You can only ever commit one lang file at a time. This is necessary so we can have all lang files always have the same exact keys.

When you commit a lang file, it is taken as the lead file. Based on this, all other lang files will be updated to include any keys that exist in the lead file, but the other files do not have. These keys then get a default value with a "TODO" to easily find and identify missing localizations.

After a successful run of the commit hook, all other lang files will be modified, which means they need to be committed as well. Each one on their own. Since you should always only work on one file at a time, these commits don't introduce changes to your leading file. You can indicate the "auto update" in the commit messages.

This is a bit more effort that is well worth it for always having consistent lang files. It also makes it easy to find missing localizations by just searching the file for "TODO".

We suggest you do not commit the other files until the very end. They are continuously updated when committing to your main file. When you are done with your file, you can commit all others once at the end. This makes up the following suggestion:

Once:

  1. Setup your working/dev environment
  2. Install all node dev dependencies (npm install) / activate pre-commit hooks
  3. Add a new lang file if not present

Workflow:

  1. Search your lang file for keys that have a value containing "TODO"
  2. Look up the localization of the key in the other files (English first)
  3. Add your localization
  4. Make commits along the way
  5. Commit all other, auto-updated lang files
  6. Push your branch and make a pull request

Guidelines for Localizations

Understanding what and who localization is for is crucial. This is how other people enjoy the game that is based on language. It's no easy feat, so thank you for supporting with your contributions.

We are not professionals and still ask you to adhere to the following guidelines at a minimum:

  • For Earthdawn specific terms: follow the terminology from official Earthdawn products, if available (e.g. Player's Guide, Game Master's Guide, etc.)
  • Make sure to use the most recent Earthdawn terminology from the official Errata and Clarifications document
  • Be aware that the localization is not for you, but every person using your language
    • Don't use insider jokes/knowledge
    • Be empathetic of different cultures, mindsets, capabilities, and the like
  • Keep it simple (for layout reasons in the program, as well as literacy of users)

Releases

We follow Semantic Versioning.

Releases are created from short-lived release/MAJOR.MINOR.PATCH branches. They are taken care of by the maintainers.

Step-by-Step Release Process

If you are a maintainer, please follow these steps to create a new release:

  1. Trigger GitHub Action Workflow "Release [1] - Prepare New Release" from the main branch
    • Choose version increase (see Semantic Versioning)
    • Creates a new release branch "release/version"
    • Updates manifests
  2. On the new release branch:
    • Final translations
    • Styling fixes
    • Severe bug fixes only
  3. Trigger GitHub Action Workflow "Release [2] - Start Release"
    • Updates changelog
    • Creates tag
    • Creates Pull Request
  4. Last check of and approve-merge of PR
  5. If all checks are successful, a new GitHub release is automatically created and pushed to the Foundry VTT package manager