From 4eb2f9230095d06b9bef372f30acc64f8ce842d1 Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Mon, 17 Jun 2024 16:19:49 -0400 Subject: [PATCH 1/9] Initial version of Best Practices - Includes a simple PR template --- .github/pull_request_template.md | 5 ++++ BEST-PRACTICES.md | 49 ++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 +- 3 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 .github/pull_request_template.md create mode 100644 BEST-PRACTICES.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..eb205d70a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,5 @@ +**Description:** + +**Testing Instructions:** + +**Related Issue:** diff --git a/BEST-PRACTICES.md b/BEST-PRACTICES.md new file mode 100644 index 000000000..1f0ee7b48 --- /dev/null +++ b/BEST-PRACTICES.md @@ -0,0 +1,49 @@ +# Best Practices + +We're glad you're considering contributing to SUSHI! Below are a few best practices that we recommend for all contributions. + +## 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. + +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. + +## Coding practices + +We recommend the following coding practices for high quality contributions: + +- Make all changes in a personal [fork](https://help.github.com/articles/fork-a-repo/) of this repository. +- Use descriptive commit messages. +- 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. + - To run the full test suite, run `npm test`. Ensure all tests are passing. +- 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. + - To run the linter on all code, run `npm run lint`. 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. + - To run the prettier on all code, run `npm run prettier`. Ensure there are no issues reported. +- Ensure any new dependencies do not contain any known security vulnerabilities + - To check for known security vulnerabilities, we recommend using [npm-audit](https://fshschool.org/). 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). + +## Making a Pull Request + +We recommend the following best practices for creating a high quality pull request: + +- Review your own PR before marking it as ready for review by others. Ensure the only code changes included are ones relevant to the feature or bugfix and that they follow the coding practices outlined above. +- Ensure your branch is up to date with master. There are a few ways you can update your branch: + - Use the "Update branch" button available once you make your PR. This is the recommended approach if you are not comfortable with merging or rebasing. + - [Merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) master into your branch. + - [Rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) your branch on master. We only recommend this approach if you are very comfortable with rebasing. +- Update the title of the PR to provide a short, descriptive summary of the PR. + - Keep the title up to date with any changes made during the review process. The title will be used in the commit message and in the release notes, so it is important that it accurately reflects the current state of the PR. +- Follow the pull request template to create a detailed PR description. + - Include a detailed description of the changes made in the PR. + - Include instructions for how to test the PR. You may want to include a link to sample FSH in FSH Online to demonstrate a bug or attach a sample project that highlights new or improved behavior. + - [Link the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) that the PR addresses. +- Follow up on any discussion on your PR. If changes are requested, make any necessary updates and comment indicating your PR is ready for re-review. +- If your PR is approved, it should be merged to master using the "[squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits)" strategy. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 538557a74..4cc5c4354 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,7 +47,7 @@ This reduces the likelihood of duplicated effort and also provides the maintaine ### Coding Practices -Code that is contributed to this project should be done in a personal fork of this repository and follow the coding practices specified in our Best Practices documentation (coming soon!). +Code that is contributed to this project should be done in a personal fork of this repository and follow the coding practices specified in our Best Practices documentation in [BEST-PRACTICES.md](BEST-PRACTICES.md). ### Before Submitting a Pull Request From d14071528663d10605228a0fc97b101d89edcbf8 Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Wed, 19 Jun 2024 11:29:29 -0400 Subject: [PATCH 2/9] Fix npm-audit link --- BEST-PRACTICES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BEST-PRACTICES.md b/BEST-PRACTICES.md index 1f0ee7b48..492b0dff6 100644 --- a/BEST-PRACTICES.md +++ b/BEST-PRACTICES.md @@ -25,7 +25,7 @@ We recommend the following coding practices for high quality contributions: - SUSHI uses [Prettier](https://prettier.io/) for code formating. - To run the prettier on all code, run `npm run prettier`. Ensure there are no issues reported. - Ensure any new dependencies do not contain any known security vulnerabilities - - To check for known security vulnerabilities, we recommend using [npm-audit](https://fshschool.org/). Run `npm audit` and ensure there are no new issues on your branch. + - 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). From db172dd4017b281678ddefe358e874e493770c89 Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Wed, 19 Jun 2024 14:13:31 -0400 Subject: [PATCH 3/9] Small updates - Add info for test coverage command - Add info for prettier and lint fix commands - Add info about ensuring new dependencies are up to date - Require use of squash and merge --- BEST-PRACTICES.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/BEST-PRACTICES.md b/BEST-PRACTICES.md index 492b0dff6..c1622e1ba 100644 --- a/BEST-PRACTICES.md +++ b/BEST-PRACTICES.md @@ -17,15 +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. - - To run the full test suite, run `npm test`. Ensure all tests are passing. + - 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. - 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. - - To run the linter on all code, run `npm run lint`. Ensure there are no issues reported. + - 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. - Follow the code formatting as enforced by the formatter configuration. - SUSHI uses [Prettier](https://prettier.io/) for code formating. - - To run the prettier on all code, run `npm run prettier`. Ensure there are no issues reported. + - 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 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. - 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). @@ -46,4 +55,4 @@ We recommend the following best practices for creating a high quality pull reque - Include instructions for how to test the PR. You may want to include a link to sample FSH in FSH Online to demonstrate a bug or attach a sample project that highlights new or improved behavior. - [Link the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) that the PR addresses. - Follow up on any discussion on your PR. If changes are requested, make any necessary updates and comment indicating your PR is ready for re-review. -- If your PR is approved, it should be merged to master using the "[squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits)" strategy. +- If your PR is approved, it will be merged to master using the "[squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits)" strategy. From a1a2e34c90adfb63f712189522f8dc5196308d96 Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Wed, 19 Jun 2024 14:35:30 -0400 Subject: [PATCH 4/9] Add information about including Zulip links in GitHub issues --- BEST-PRACTICES.md | 1 + CONTRIBUTING.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/BEST-PRACTICES.md b/BEST-PRACTICES.md index c1622e1ba..a942de471 100644 --- a/BEST-PRACTICES.md +++ b/BEST-PRACTICES.md @@ -5,6 +5,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). 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4cc5c4354..92ab23573 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,8 @@ When submitting a bug report, please try to provide as much detail as possible. - relevant outputs - any other information you deem relevant +When creating or contributing to an issue, please include a link to any relevant discussion threads on [Zulip](https://chat.fhir.org) (see below). + Please note that the GitHub issue tracker is _public_; any issues you submit are immediately visible to everyone. For this reason, do _not_ submit any information that may be considered sensitive. ## Zulip From 7c4b6fee2205e44567d370c0c1b861c3ba6a4746 Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Wed, 19 Jun 2024 15:20:11 -0400 Subject: [PATCH 5/9] Move bullet points around for clarity, simplify suggestions for creating issues --- BEST-PRACTICES.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) 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). From 998754bd8492d98a2c261d85eaedae82cc74320d Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Wed, 19 Jun 2024 15:31:21 -0400 Subject: [PATCH 6/9] Fix typo --- BEST-PRACTICES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BEST-PRACTICES.md b/BEST-PRACTICES.md index 5732021fc..0ea0f0982 100644 --- a/BEST-PRACTICES.md +++ b/BEST-PRACTICES.md @@ -26,7 +26,7 @@ We recommend the following coding practices for high quality contributions: - 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. + - SUSHI uses [Prettier](https://prettier.io/) for code formatting. - 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 there are no issues reported. From 2736c43bb6cdf23ca6649dce0dbe95d985b97843 Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Fri, 21 Jun 2024 10:56:51 -0400 Subject: [PATCH 7/9] Update documentation for using Zulip vs GitHub issues - Recommend use of Zulip for discussion - Note that if the conversation concludes that changes to the tooling are required, a GitHub issues should be created --- BEST-PRACTICES.md | 6 +++--- CONTRIBUTING.md | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/BEST-PRACTICES.md b/BEST-PRACTICES.md index 0ea0f0982..062143b0c 100644 --- a/BEST-PRACTICES.md +++ b/BEST-PRACTICES.md @@ -2,13 +2,13 @@ We're glad you're considering contributing to SUSHI! Below are a few best practices that we recommend for all contributions. -## Before contributing +## 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. See the [Contribution Policy](CONTRIBUTING.md#issues) to learn more about creating issues. +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. It may also be useful, but is not required, to start a Zulip conversation around the feature or bug. See the [Contribution Policy](CONTRIBUTING.md#zulip) to learn more about Zulip. 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. -## Coding practices +## Coding Practices We recommend the following coding practices for high quality contributions: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92ab23573..2f221d126 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,6 +41,8 @@ Before starting a new conversation, please check for earlier discussions on a si When starting a new conversation, please use a descriptive topic and include as much detail as possible. +If you are looking for feedback or discussion around an issue, we recommend using Zulip. The FSH community is active on Zulip, and it is the best place to have in-depth discussions and ask questions about the FSH tooling. If the discussion on Zulip determines that a change is required in SUSHI, you should create a GitHub issue to track it. The GitHub issue should include a link to the relevant Zulip discussion thread, and it is best practice to provide a link to the GitHub issue on the Zulip thread. While Zulip is very useful for discussion, GitHub issues are the system of record for changes to SUSHI. + ## Code Contributions If you are planning to work on a reported bug, suggestion, or feature request, please comment on the relevant issue to indicate your intent to work on it. From 301ccea676976b54a1539cc94dfec04360e0a84b Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Fri, 21 Jun 2024 11:49:48 -0400 Subject: [PATCH 8/9] Further clarify GitHub issues vs Zulip --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f221d126..7adcaf634 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,7 +15,7 @@ Before making a contribution, please familiarize yourself with this document, as ## Issues -We use GitHub issues to track bug reports, comments, suggestions, questions, and feature requests. +We use GitHub issues to track bug reports, comments, suggestions, questions, and feature requests. If you need help with using FHIR Shorthand or its tools, however, you may want to consider posting on Zulip first (see below). Questions posted on Zulip will reach a broader set of FSH users and will likely receive more timely responses. Requests for specific changes, however, should be submitted as GitHub issues so they can be formally tracked. Before submitting a new issue, please check to make sure a similar issue isn't already open. If one is, contribute to that issue thread with your feedback. From 5fe2faa0f4b97343aa93a22a21557254f6f91412 Mon Sep 17 00:00:00 2001 From: Julia Afeltra Date: Fri, 21 Jun 2024 11:51:20 -0400 Subject: [PATCH 9/9] remove link for consistency --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7adcaf634..d6a44c1c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,7 @@ When submitting a bug report, please try to provide as much detail as possible. - relevant outputs - any other information you deem relevant -When creating or contributing to an issue, please include a link to any relevant discussion threads on [Zulip](https://chat.fhir.org) (see below). +When creating or contributing to an issue, please include a link to any relevant discussion threads on Zulip (see below). Please note that the GitHub issue tracker is _public_; any issues you submit are immediately visible to everyone. For this reason, do _not_ submit any information that may be considered sensitive.