Skip to content

Latest commit

 

History

History
111 lines (70 loc) · 3.91 KB

CONTRIBUTING.md

File metadata and controls

111 lines (70 loc) · 3.91 KB
Raw

Contributing

Before beginning, please make sure you have the following tools installed.

Installation

git clone https://github.com/RetroAchievements/api-js.git
cd retroachievements-api-js
pnpm install

Local development

This project includes a __playground.ts file for testing any local changes. To get started, open the file and replace these lines with values pertinent to your user account on RetroAchievements:

const username = "myUsername";
const webApiKey = "myWebApiKey";

You can now modify the playground file how you see fit to test your changes. To run the file in watch mode, execute the following command in your terminal:

pnpm dev

Commit messages

This project uses linted commit messages. While this can be annoying, releases are automatically cut based on the kind of commit you write. This ensures major, minor, and patch releases are versioned correctly on npm. We use conventional commits.

Example commit messages:

"fix: remediate issue in getActiveClaims()"
"feat: add new getUserExtendedSummary() function"
"docs: update getUserSummary page"
"test: increase coverage for some functions"

Based on the type (the word before the colon), the release can be correctly versioned. For example, a commit message with the word "fix" will automatically be understood that a patch release (x.x.1) should be cut. A commit message with the word "feat" will automatically be understood that a minor release (x.1.x) should be cut.

Code Formatting and Linting

Prettier is used for code style. ESLint with a strict set of anti-code smell rules is used for linting. All ESLint rules have automatic fixers so you don't have to stress about what rules your code follows.

To manually run Prettier, do:

pnpm format:write

To manually run ESLint, do:

pnpm lint:fix

This works but is cumbersome. It is recommended that you set your editor to run Prettier and ESLint automatically on save.

How to set up Prettier auto-format on save for VSCode How to set up ESLint auto-fix on save for VSCode

Tests

Given that this library is an official reference implementation, we strive for high code coverage. New code should always have tests to accompany it.

To run the current suite of tests, in the terminal execute:

pnpm test

If you're actively writing tests, you can use watch mode like:

pnpm test --watch

Take note of the ARRANGE, ACT, ASSERT pattern followed throughout the testing suite and be sure to use it in any new tests so they are easy to understand for future maintainers.

Building

This project uses microbundle for builds. This was specifically chosen over other solutions due to microbundle's special optimizations for packaging libraries (vs a solution like Vite which is built more for apps).

You can build the app using:

pnpm build

Opening a PR

Before opening a PR, the following are good things to check for:

  • Does pnpm verify pass successfully?
  • Does any new code have tests?
  • Is new code documented on the VitePress site?

How to release to npm

If you are a RetroAchievements org member, you should be able to release a new package to npm.

  1. Change the package version number in package.json. Respect semantic versioning: [major].[minor].[patch]. A major release usually assumes breaking changes.

  2. Run pnpm build.

  3. Run npm publish --access public.