Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (83 loc) · 7.19 KB

CONTRIBUTING.md

File metadata and controls

118 lines (83 loc) · 7.19 KB

How to contribute

We love pull requests. And following these guidelines will make your pull request easier to merge.

If you want to contribute but don’t know what to do, take a look at these two labels: help wanted and good first issue.

Use the GitHub interface for simple documentation changes, otherwise follow the steps below.

⚠️ IMPORTANT NOTE ⚠️

All contributions are expected to be of the highest possible quality! That means the PR is thoroughly tested and documented, without relying on blindly generated AI code and documentation. We will not consider or merge PRs that do not comply with these rules! A single typo PR would be automatically closed, except for major refactoring for the latest or next versions.

Development workflow

  • If it’s your first pull request, watch this amazing course by Kent C. Dodds

  • Fork the repository and clone your fork

  • Checkout the develop branch (or next-version if it was more recently updated)

  • To install dependencies, run:

    npm install

  • To build your changes, run:

    npm run build

  • Don’t forget to add tests and update the documentation for your changes.

  • Please update the npm lock file (package-lock.json) if you add or update dependencies.

Running tests

Run linters and tests:

npm test

Or run tests in watch mode:

npm test --watch

By default, the tests are executed in your local Devnet, and everything should run automatically.

If you want to use a specific RPC node, you have to set some global variables before executing the tests:

export TEST_RPC_URL=http://192.168.1.44:9545/rpc/v0_9 # example of a Pathfinder node located in your local network
export TEST_RPC_URL=https://starknet-sepolia.public.blastapi.io/rpc/v0_9 # example of a public Sepolia testnet node
export TEST_ACCOUNT_ADDRESS=0x065A822f0000000000000000000000000c26641
export TEST_ACCOUNT_PRIVATE_KEY=0x02a80000000000000000000000001754438a

The global variables above will only be valid for some of the tests. The recommended and more straightforward approach is to use Docker. Do the following steps:

  • Install Docker (it can also be installed via a package manager, e.g., brew for Mac)
  • Run Docker on your machine (open the application)
  • Run docker pull shardlabs/starknet-devnet-rs:latest in your terminal, or go to starknet-devnet-rs, copy and run the docker pull command from the appropriate tag
  • Run the tests

Commit messages

For commit messages use Conventional Commits, like so: feat(scope): topic

Note that the feat and fix commit messages are used for compiling the changelog. They should be relative to the current state of the target branch they should be merged into, and not the feature branch where committed.

Example of incorrect commit messages:

fix: repair some bug
fix: rectify failing test
fix: adjust formatting
fix: add comments
fix: repair some other bug

Example of correct commit messages:

fix: repair some bug
test: rectify failing test
chore: adjust formatting
chore: add comments
fix: repair some other bug

Branches and pull request targets

Branch NPM Tag PR Target
develop next For the most common pull requests, such as bug fixes, feature additions, documentation changes, etc., target the develop branch.
beta beta For major changes that markedly transform the existing API or significantly alter the behavior of some functionality, ensure that the corresponding commits contain appropriate Conventional Commits breaking change notations, and as the pull request target, select the beta branch.
main latest Should only be used by maintainers.

After a develop/next version has proven to be stable, it is promoted to latest by merging into main.
maintenance/x.y
maintenance/x.y.z		 maintenance Should only be used by maintainers.

Branches with the maintenance prefix are used for applying adjustments to versions that have been merged into main but are no longer the latest release. They should be created from the corresponding Git tag and can have either minor or patch version specificity.

Other notes

  • If you have commit access to the repository and want to make a big change or are unsure about something, make a new branch and open a pull request.
  • We’re using Prettier to format code, so don’t worry much about code formatting.
  • Don’t commit generated files, like minified JavaScript.
  • Don’t change the version number or changelog.
  • Use npm run test:coverage for a complete project test coverage.
  • Use, for example, npm run test:coverage __tests__/utils/uint256.test.ts for a single file coverage.
  • Use npm run ts:coverage to check the global type coverage rate and npm run ts:coverage:report to generate a complete report (summary displayed in the console, full HTML report available in the coverage-ts folder by launching ./coverage-ts/index.html in your browser) and find files having low coverage.

Need help?

If you want to contribute but have any questions, concerns, or doubts, feel free to ping maintainers. Ideally, create a pull request with WIP (Work in progress) in its title and ask questions in the pull request description.

You can also ask your query on our dedicated channel for Starknet.js on the Starknet Discord