Skip to content

Latest commit

 

History

History
133 lines (94 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

133 lines (94 loc) · 3.5 KB

Contributing

We welcome contributions that align with the projects vision. See the ./README.md for an overview of what this project aims to be.

Preferably backwards compatibility should be preserved, but given the alpha status of the project we won't hold ourselves to that just yet.

We use Github issues to track work, though directly raising a PR with a detailed description is fine too.

Setup

  1. Install a node version manager that respects .nvmrc files, such as fnm
  2. Enable corepack using corepack enable
  3. Install devDependencies using yarn

Workflow

See package.json for available scripts.

Main ones of interest are build, test, lint. E.g:

yarn build
yarn test
yarn lint
yarn format

To regenerate the integration tests:

yarn integration:generate

And to build them / check the code output is valid:

yarn integration:validate

There's also a ci-pipeline script that can be used as a pre-push check, e.g:

yarn ci-pipeline && git push --force-with-lease

Typescript Conventions

yarn build

We strive for robust type safety, both in the library and the code it outputs. That said we're also pragmatic - if it makes sense to use an any we will, but we'll limit the scope to avoid its impact. Eg: the brief use of ts-ignore / any in the fetch runtime here

Linting / Formatting

yarn lint
yarn format

We use biome for formatting, and linting, largely sticking to the recommended rules. The config can be seen here ./biome.json

Testing

yarn test
yarn integration:generate && yarn integration:validate

We have two types of testing in play:

  • Unit tests using jest
  • Integration tests

The unit testing is currently a bit on the "light" side - the project started as a fun experiment on a weekend and there is still some back filling to do. New code, and particularly bug fixes should include unit tests.

There is also a heavy reliance on integration tests, where we use the openapi specifications for large API surfaces to run the code generation and check that the result builds, currently this includes:

  • Github API
  • Stripe API
  • Okta API (partial)
  • Petstore API (from Swagger)
  • A Todo List API (written for this repo, showcases definitions split across multiple files)

At this stage we don't actually execute the code generated for these API's, but this would be a nice improvement for the future. The Github client in particular gets a fair amount of use for automating tasks against my workplace's Github organisation.

Publishing

For now, publishing the package is a manual process. There are two scripts to assist:

# Publish a pre-release, eg: 0.0.2-alpha.107
yarn publish:alpha
# Publish a release, eg: 0.0.1
yarn publish:release

These will build and test before asking for publish confirmation.

After publishing a release, manually create a release in Github.