Skip to content
This repository has been archived by the owner on Apr 21, 2024. It is now read-only.

Latest commit

 

History

History
133 lines (105 loc) · 5.17 KB

CONTRIBUTING.adoc

File metadata and controls

133 lines (105 loc) · 5.17 KB

Contribution Guidelines

Thank you for investing your time in contributing to our project! If you are a first-time contributor to this project, please take a look at the Get Started section 😀

Caution
 All commands in this README document are to be executed from the project root directory (where this document resides).

Get Started

This project uses the zero-install feature of the Yarn package manager. Upon cloning the Git repository, the .yarn/cache directory already contains a cache of the third-party dependencies, effectively replacing the usual node_modules directory.

Install Node.js and Yarn

  • macOS and Linux users should install Node.js via Node Version Manager and opt for Yarn via Corepack:

    curl https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
nvm install --lts
corepack enable yarn
yarn run setup

  • Windows users should install Node.js via Windows Package Manager and install Yarn via npm (which is actually a workaround until Corepack supports Windows):

    winget install OpenJS.NodeJS.LTS
npm install --global yarn
yarn run setup

Prepare Git

  1. Generate an SSH key with the Ed25519 algorithm, for example using ssh-keygen or 1Password, and add it to the SSH agent on your computer. If you already have an SSH key on your computer, you may skip this step.

    ssh-keygen -t ed25519 -f "$HOME/.ssh/<my-ssh-key>"
ssh-add ~/.ssh/<my-ssh-key>

    • Windows users must instruct Git to use Microsoft OpenSSH as the SSH agent:

      git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

  2. Grab the public key. It appears like ssh-ed25519 AAAAC3(…​).

    cat ~/.ssh/<my-ssh-key>.pub

  3. Register the public key in GitHub as a signing key.

  4. Obtain your noreply email address on GitHub. It appears like <id+username>@users.noreply.github.com.

  5. Declare your identity within the scope of this repository and use the public key to sign your commits:

    git config user.name "<FirstName> <LastName>"
git config user.email "<id+username>@users.noreply.github.com"
git config user.signingkey "ssh-ed25519 AAAAC3<PublicKey>"
git config gpg.format "ssh"
git config commit.gpgsign "true"
git config tag.gpgsign "true"

Open the Project in IntelliJ IDEA

  1. Open the project directory:

    idea .

  2. Follow the popup message to install the recommended plugins automatically. Alternatively, go to File › Settings › Plugins and install them manually.

  3. Go to File › Settings › Languages & Frameworks › Node.js. Select the appropriate Node.js interpreter and enable coding assistance.

Open the Project in Visual Studio Code

  1. Open the project directory:

    code .

  2. Go to View › Extensions and search for @recommended. Install the recommended extensions.

Tasks

The scripts field in package.json defines a set of work tasks. Corresponding configurations for IntelliJ IDEA and Visual Studio Code are located in .idea/runConfigurations and .vscode/tasks.json, respectively.

Validate the Software Quality

  • Source code formatting via Prettier (validate.format).

    • validate.format.fix reformats the files accordingly.

    • validate.format.nocache runs validate.format without caching which is encouraged after an adjustment to the formatting configuration.

Troubleshooting

IntelliJ IDEA: Cannot Resolve External Modules

If import statements are full of squiggly red lines, and IntelliJ IDEA claims that external modules or third-party dependencies are not installed, try the following steps:

  1. In the project root directory, delete the .yarn directory and the .pnp.cjs, .pnp.loader.mjs, and yarn.lock files.

  2. Roll back the deletion in Git to restore the files. This triggers re-indexing in IntelliJ IDEA.

  3. Go to Help › Find Action and search for Restart TypeScript Service.