diff --git a/BEST-PRACTICES.md b/BEST-PRACTICES.md index a942de471..5732021fc 100644 --- a/BEST-PRACTICES.md +++ b/BEST-PRACTICES.md @@ -4,8 +4,7 @@ We're glad you're considering contributing to SUSHI! Below are a few best practi ## Before contributing -Before contributing a feature or a bugfix, we recommend creating a GitHub issue if one does not exist. This allows the community to provide feedback on why an issue may be occurring or provide additional insight into a suggested feature. -When creating a GitHub issue, include a description of the feature or bug, any steps needed to demonstrate the issue, and any links to relevant discussion threads on [Zulip](https://chat.fhir.org). +Before contributing a feature or a bugfix, we recommend creating a GitHub issue if one does not exist. This allows the community to provide feedback on why an issue may be occurring or provide additional insight into a suggested feature. See the [Contribution Policy](CONTRIBUTING.md#issues) to learn more about creating issues. If a GitHub issue already exists for what you are planning to contribute, we recommend commenting on the issue to indicate that you are working on an implementation to avoid duplication of work. @@ -18,24 +17,24 @@ We recommend the following coding practices for high quality contributions: - Prefer self-explanatory code as much as possible, but provide helpful comments for complex expressions and code blocks. - Add unit tests for any new or changed functionality, and update any existing tests that are impacted by your changes. - SUSHI uses [Jest](https://jestjs.io/) as a testing framework. - - Ensure all tests are passing. Ensure that code coverage of the new code is complete. - To run the full test suite, run `npm test`. - To review the test coverage report, run `npm run coverage` after running the full test suite. + - Ensure all tests are passing. Ensure that code coverage of the new code is complete. - Follow the code style and conventions as enforced by the lint configuration and as evidenced by the existing code. - SUSHI uses [ESLint](https://eslint.org/) for code linting. - - Ensure there are no issues reported. - To run the linter on all code, run `npm run lint`. - To automatically fix as many issues as possible, run `npm run lint:fix`. This uses ESLint's [--fix](https://eslint.org/docs/latest/use/command-line-interface#fix-problems) option. + - Ensure there are no issues reported. - Follow the code formatting as enforced by the formatter configuration. - SUSHI uses [Prettier](https://prettier.io/) for code formating. - - Ensure there are no issues reported. - To run Prettier on all code, run `npm run prettier`. - To automatically rewrite files in order to resolve formatting issues, run `npm run prettier:fix`. This uses Prettier's [--write](https://prettier.io/docs/en/cli.html#--write) option. -- Ensure any new dependencies do not contain any known security vulnerabilities - - To check for known security vulnerabilities, we recommend using [npm-audit](https://docs.npmjs.com/cli/v10/commands/npm-audit). Run `npm audit` and ensure there are no new issues on your branch. + - Ensure there are no issues reported. - Ensure any new dependencies use the latest published version. - If a new dependency is required but the latest published version cannot be used, add the dependency and reason for not updating to [DEPENDENCY-NOTES.md](DEPENDENCY-NOTES.md). - To check the latest published version, check the versions of the package on [npm](https://www.npmjs.com/) or use [npm-outdated](https://docs.npmjs.com/cli/v10/commands/npm-outdated). Run `npm outdated` and check that the new dependency is not listed in the output. +- Ensure any new dependencies do not contain any known security vulnerabilities + - To check for known security vulnerabilities, we recommend using [npm-audit](https://docs.npmjs.com/cli/v10/commands/npm-audit). Run `npm audit` and ensure there are no new issues on your branch. - Update documentation to reflect any user-facing changes. - Documentation updates may include, but are not limited to, the project [README](README.md) and [FSH School](https://fshschool.org/). - If changes are required to FSH School, follow the instructions for contributing in the [project repository](https://github.com/FSHSchool/site).