CONTRIBUTING.md

# Contributing to FC: Pregmod

First off, thanks for taking the time to contribute!

If there is anything you don't understand feel free to ask. Many of the more advanced tools are also not required for
fixing small typos or simple bugs.

## Environment

### Requirements

To effectively work on the project the following tools are required:

* `Git`
* `Node.js` or another npm client
* an IDE capable of working with JavaScript, TypeScript and CSS. `VS Code` is one option.
* Java Runtime Environment, minimum JRE8

### Setting everything up

0. Clone the project from GitGud.io ([Detailed Git setup and work cycle](devNotes/gitSetup.md))
1. Open a terminal (Linux) / cmd window (Windows) and navigate to the `fc-pregmod` root directory.
2. Run `npm install`
3. Open the directory in your preferred IDE
4. Configure your IDE to use ESLint and the type checking capabilities of the TypeScript compiler.

## Compiling

While you can compile it like usual (`compile.bat`/`compile.sh`/`make`), there is also a `Gulp script` that creates
source files for easier debugging. Other than that there are no differences between compiling for development or
compiling for playing the game.

# Code

## Code style

Generally the code style is based on our `.eslintrc.json`. If your IDE has an auto format feature it can often read the
rules from `.eslintrc.json`.

### Important Rules

* use spaces after commas
* do not omit semicolons
* no empty blocks
* don't pad blocks with blank lines
* prefer strict equality/inequality
* etc.

### Documentation

It's a good idea to provide meaningful documentation for new functions and classes where possible. We follow
Typescript's [JSDoc](https://jsdoc.app) type dialect for the most part (and we provide a Typescript configuration and
auxiliary type definition files if you'd like to use it yourself – it's pretty nifty). Don't worry too much about
specific type syntax if you can't make TS work or don't understand it, someone else will probably fix it for you as long
as you've made the intent clear in some form of JSDoc.

### Naming conventions

* JavaScript variable and function names should be `camelCase`.

```js
// bad
let foobar;
let Foobar;
let FooBar;

// good
let fooBar;
```

* Enum members should be `ALLCAPS`.

```ts
// bad
enum Foo {
  bar = 'bar',
  Baz = 'baz',
}

// good
enum Foo {
  BAR = 'bar',
  BAZ = 'baz',
}
```

This also applies to JavaScript objects that are used as enums.

```js
// bad
/** @enum {string} */
const foo = {
  bar: 'bar',
  Baz: 'baz',
}

// good
/** @enum {string} */
const foo = {
  BAR: 'bar',
  BAZ: 'baz',
}


// better
/** @enum {string} */
const Foo = {
  BAR: 'bar',
  BAZ: 'baz',
}
```

* JavaScript classes and namespaces should be `PascalCase`.

```js
// bad
class foo {}
class FOO {}
App.foo.bar();

// good
class Foo {}
App.Foo.bar();
```

* CSS classes are `kebob-case`.

```css
/* bad */
.fooBar {}
.FOO-BAR {}

/* good */
.foo-bar {}
```

New code should generally get organized into the `App` namespace. See `js/002-config/fc-init-js.js` for a rough outline.

## JavaScript Features

* Avoid using very new JavaScript features
  * Generally, we're currently targeting ECMAScript 2018, though we use a few widely-implemented ECMAScript 2019
    features, like `globalThis`.
* Conversely, do use modern features, it's not 2010 anymore and we don't try to support Internet Explorer or anything
  stupid like that.
  * use `let`/`const` rather than `var`
  * prefer fat arrow functions to inline long-form functions
  * etc.

## Code quality

There are three main tools used to ensure good code quality, `ESLint`, `TypeScript Compiler (tsc)` and a custom sanity
check.

`ESLint` and `tsc` can be setup in most IDEs aimed at web development to show errors while editing the file.

Contributions should generally not add any new sanity check errors, and it's especially important to check this if
you're making changes to .tw files.
Use `./compile.sh --dry --sanity` or the short hand `./compile.sh -d -s` on linux or mac.
On Windows run `compile_debug+sanityCheck.bat`.
It searches for common spelling errors and syntax errors in the twine files. Don't worry about preexisting
errors, it's not totally clean as is and there are a few false positives.

# Further Reading

## Wiki Files

* Writing Guides
  * [Twine (Twine is being phased out of the project however the concepts are still relevant)](devNotes/scene-guide.txt)
  * [JavaScript](devNotes/jsEventCreationGuide.md)
* [Exception handling](devNotes/exceptions.md)
* [Sanity check](devNotes/sanityCheck.md)
* [Slave List](devNotes/slaveListing.md)
* [Pronouns](devNotes/Pronouns.md)
* External function documentation
  * [Eyes](devNotes/eye functions.md)
  * [Limbs](devNotes/limb functions.md)
  * [Standalone functions](devNotes/standaloneFunctions.md)
  * [Some potentially useful JS functions](devNotes/usefulJSFunctionDocumentation.txt)
  * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616)

## Useful issues

* [Setting up VS Code](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2448)
* [Classes in Game State](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/696)
* [Self executing functions](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2325)
* [Sort a map](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2642)