Contributing

When it comes to open source, there are different ways you can contribute, all of which are valuable. Here's few guidelines that should help you as you prepare your contribution.

Table of Contents

• Initial Steps
• Development
  • Environment Variables
  • Commands
• Contributing Translations
  • How to Contribute Translations
  • Adding a New Language
  • Verifying and Finalizing Translation Changes
• Submitting a Pull Request
• Extra Notes

Initial Steps

Before you start working on a contribution, please check the issues page. It's possible someone else is already working on something similar, or perhaps there is a reason that feature isn't implemented. The maintainers will point you in the right direction.

If you still have questions, please check the Discord

Development

The following steps will get you setup to contribute changes to this repo:

• Fork the repo
• Clone your forked repository: git clone git@github.com:{your_username}/pawn-appetit.git
• Enter the directory: cd pawn-appetit
• Create a new branch off the master branch: git checkout -b your-feature-name
• Install dependencies pnpm i
• Open the code in your preferred IDE and contribute your changes

It is recommended take a look at the Commands and Extra Notes sections before starting.

Environment Variables

Create a .env file in the project root to configure the following variables before running the app:

Variable	Required	Description
VITE_SERVER_URL	Yes (for database downloads)	Base URL of the file server used to download game and puzzle databases. Without this, the "Web" tab in the Add Database dialog will show an error and downloads will be unavailable.

Example .env:

VITE_SERVER_URL=https://example.com/databases

Note: VITE_SERVER_URL is set automatically in CI via a GitHub Actions repository variable (SERVER_URL). When contributing locally, you must set it manually if you need to test database downloads.

Commands

pnpm i

• Installs all dependencies

pnpm dev

• Starts the app in development mode to see changes in real time

pnpm test

• Runs all tests, generating a report

pnpm format

• Formats the project according to the project guidelines

pnpm lint:fix

• Lints the project according to the project guidelines

pnpm build

• Builds the entire app from source. The built app can be found at src-tauri/target/release

Contributing Translations

Help us make Pawn Appétit accessible to everyone by contributing a new translation or improving an existing one! Your contributions are valuable and easy to make.

How to Contribute Translations

All translation files are located in the src/locales/ directory.

Adding a New Language

1. Create the new file: Copy an existing translation file, such as en/common.json, and rename it using your language's code (e.g., hy/common.json for Armenian).
2. Translate the text: Open your new file and translate all the text values within it.
3. Add the language to i18n.init({...}): Open index.tsx and the new language to the list of imports and to i18n.init({...}).

For example:

import fr from "./locales/fr";
+import hy from "./locales/hy";
import it from "./locales/it";

i18n.use(initReactI18next).init({
  resources: {
    ...,
    fr-FR: fr,
 +  hy-AM: hy,
    it-IT: it,
    ...
  }

Verifying and Finalizing Translation Changes

1. Run the update script: After making your changes, run the following command to automatically check for and add any missing translation keys with placeholder values.

   pnpm scripts/update-missing-translations.ts
   

2. Update the README: Use this script to ensure the README is up to date with the latest translation information.

   pnpm scripts/update-readme.ts
   

3. Test your changes: Start the development server to see your translations in action and make sure everything looks correct.

   pnpm dev
   

Submitting a Pull Request

• Implement your contributions (see the Development section for more information)
• Before submitting a PR, first build the app using pnpm tauri build -b none and check every feature you've contributed to.
• Format and lint your code using pnpm format followed by pnpm lint:fix
• If you're contributing translations, follow the steps in Verifying and Finalizing Translation Changes
• Go to the comparison page and select the branch you just pushed in the compare: dropdown
• Submit the new PR. The maintainers will follow up ASAP.

Extra Notes

The app uses the Rust language for interacting with the filesystem, chess engines and databases, and React with Vite (using TypeScript, of course) for displaying the GUI.

• The Rust code can be found in src-tauri/src
• The React code can be found in src