Skip to main content

How to Contribute

Reporting Bugs​

If you find a bug, we strongly encourage you to report it to the project maintainers. You can do this by creating a new issue on the project's issue tracker, or by sending a pull request with a fix for the bug. It is always helpful to provide as much information as possible when reporting bugs, and it would help a lot if you could provide an example that demonstrates the bug.

I would like to contribute code - how do I do this?​

Fork the repository, make your change and submit a pull request. Before submitting the pull request:

  • make sure that your changes are well tested and that you have updated the project's documentation.
  • make sure your tests (yarn run test) and build (yarn run build) are properly working locally on your machine and make sure they all pass

Any guidance on submitting changes?​

While we do appreciate code contributions, triaging and integrating contributed code changes can be very time consuming. Please consider the following tips when working on your pull requests:

  • Functionality is appropriate for the repository. Consider posting on the forum if you are not sure.
  • Code quality is acceptable. We don't have coding standards defined, but make sure it passes ESLint and looks like the rest of the code in the repository.
  • Quality of design is acceptable. This is a bit subjective so you should consider posting on the forum for specific guidance.
  • The scope of the pull request is not too large. Please consider separate pull requests for each feature as big pull requests are very time consuming to understand.
  • We will provide feedback on your pull requests as soon as possible. Following the tips above will help ensure your changes are reviewed.

My changes require updating dependencies in the package.json files - what is the process for doing this?​

In general you will typically not be updating the various package.json files. But for the case when you do, you will have to also update the various Cornerstone3D lock files and as such you will have to do both a yarn and bun install without the --frozen-lockfile flag.

danger

Updating the package.json files must be done with care so as to avoid incorporating vulnerable, third-party packages and/or versions. Please research the added packages and/or versions for vulnerabilities.

Here is what you should do when adding new packages and/or versions prior to committing and pushing your code:

  1. Do your due diligence researching the added packages and/or versions for vulnerabilities.
  2. Update the package.json files.
  3. Execute yarn run install:update-lockfile. This updates both the yarn.lock and the bun.lock files.
  4. Execute yarn run audit for a last security check. This runs both yarn audit and bun audit.
  5. Include both the yarn.lock and bun.lock files as part of your commit.

If any of your research or auditing for vulnerabilities find HIGH risk vulnerabilities do NOT commit or push your changes! Low and moderate risk vulnerabilities are acceptable.