From da8981b8f4a8a900b4c25523e8be0d6837981be0 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Fri, 15 Nov 2024 14:36:18 -0500 Subject: [PATCH 01/10] move appropriate stuff out to contributing --- CONTRIBUTING.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++- README.md | 71 ------------------------------- 2 files changed, 110 insertions(+), 72 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab4c9dd5168b..6c32aaa86401 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,76 @@ Welcome, and thank you for your interest in contributing to iTwin.js! There are many ways to contribute. The goal of this document is to provide a high-level overview of how you can get involved. +- [Contributing to iTwin.js](#contributing-to-itwinjs) + - [Repo Setup](#repo-setup) + - [Source Code Edit Workflow](#source-code-edit-workflow) + - [Other NPM Scripts](#other-npm-scripts) + - [Asking Questions](#asking-questions) + - [Providing Feedback](#providing-feedback) + - [Reporting Issues](#reporting-issues) + - [Look For an Existing Issue](#look-for-an-existing-issue) + - [Writing Good Bug Reports and Feature Requests](#writing-good-bug-reports-and-feature-requests) + - [Follow Your Issue](#follow-your-issue) + - [Contributing Guidelines](#contributing-guidelines) + - [Contributor License Agreement (CLA)](#contributor-license-agreement-cla) + - [Pull Requests](#pull-requests) + - [Types of Contributions](#types-of-contributions) + - [Frequently Asked Questions](#frequently-asked-questions) + - [Rush commands take too long, is there a way to speed up my contribution workflow?](#rush-commands-take-too-long-is-there-a-way-to-speed-up-my-contribution-workflow) + - [Do I have to rebuild all packages in the repo, even those I didn't work on?](#do-i-have-to-rebuild-all-packages-in-the-repo-even-those-i-didnt-work-on) + - [A subdirectory can not find a node\_modules file or directory](#a-subdirectory-can-not-find-a-node_modules-file-or-directory) + - [Updating dependencies/devDependencies on packages within the monorepo](#updating-dependenciesdevdependencies-on-packages-within-the-monorepo) + - [Updating dependencies/devDependencies on packages external to monorepo](#updating-dependenciesdevdependencies-on-packages-external-to-monorepo) + +## Repo Setup + +This repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) that holds the source code to multiple iTwin.js npm packages. It is built using [Rush](http://rushjs.io/). + +Each package has its own **node_modules** directory that contains symbolic links to *common* dependencies managed by Rush. + +1. Install dependencies: `rush install` +2. Clean: `rush clean` +3. Build source: `rush build` +4. Run tests: `rush cover` + +The `-v` option for `rush` is short for `--verbose` which results in a more verbose command. + +The above commands iterate and perform their action against each package in the monorepo. + +## Source Code Edit Workflow +Once you've set up the repo, you can move on to making changes to the source code by following the steps below: +1. At the root of the repo, run `git checkout -b ""` +2. Make source code changes +3. Rebuild the repo by running `rush build` +4. Ensure unit tests pass when run locally: `rush cover` +5. Ensure linting passes when run locally: `rush lint` +6. Locally commit changes: `git commit` (or use the Visual Studio Code user interface) +7. Repeat steps 1-4 until ready to push changes +8. Check for API signature changes: `rush extract-api`. This will update the signature files, located in `common/api`. **Note:** before doing this, first do the following: + - Be sure that your branch is up to date with the target branch (i.e. `git merge origin/master`) + - Cleanup your build output: `rush clean` + - Rebuild the project: `rush build` +9. Review any diffs to the API signature files in the `common/api` directory to ensure they are compatible with the intended release of the package. + - If any differences are in packages not modified on this branch, revert the changes before committing. +10. Add changelog entry (which could potentially cover several commits): `rush change` +11. Follow prompts to enter a change description or press ENTER if the change does not warrant a changelog entry. If multiple packages have changed, multiple sets of prompts will be presented. If the changes are only to non-published packages (like **display-test-app**), then `rush change` will indicate that a changelog entry is not needed. +12. Completing the `rush change` prompts will cause new changelog entry JSON files to be created. +13. Add and commit the changelog JSON files and any API signature updates. +14. Publish changes on the branch and open a pull request. + +> If executing scripts from `package.json` files in any of the subdirectories, we recommend using [`rushx`](https://rushjs.io/pages/commands/rushx/) over `npm`. + +If using the command line, steps 8 through 11 above can be completed in one step by running `rushchange.bat` from the imodeljs root directory. +Only use `rushchange.bat` if none of the changes require a changelog entry. +> Note: The CI build will break if changes are pushed without running `rush change` and `rush extract-api` (if the API was changed). The fix will be to complete steps 6 through 11. + +Here is a sample [changelog](https://github.com/microsoft/rushstack/blob/master/apps/rush/CHANGELOG.md) to demonstrate the level of detail expected. + +### Other NPM Scripts + +1. Build TypeDoc documentation for all packages: `rush docs` +2. Build TypeDoc documentation for a single package: `cd core\backend` and then `rushx docs` + ## Asking Questions Have a question? @@ -63,7 +133,7 @@ They will simply ask for more information! You may be asked to clarify things or try different approaches, so please follow your issue and be responsive. -## Contributions +## Contributing Guidelines We'd love to accept your contributions to iTwin.js. There are just a few guidelines you need to follow. @@ -92,3 +162,42 @@ We welcome contributions, large or small, including: If you would like to contribute new APIs, please check the [CODEOWNERS](https://github.com/iTwin/itwinjs-core/blob/master/.github/CODEOWNERS) file to ensure your contributions align with the package owner's and project goals. Thank you for taking the time to contribute to open source and making great projects like iTwin.js possible! + +## Frequently Asked Questions + +### Rush commands take too long, is there a way to speed up my contribution workflow? + +If your source code change only impacts the subdirectory you are working on, you can use a package manager to run local commands, without affecting other packages. + +Eg. I add a new method within `core/frontend`, also adding a relevant unit test in that folder's `src/test`. I can navigate to the root of that subdirectory, and run `pnpm build`, followed by `pnpm test` or `pnpm cover`. + +### Do I have to rebuild all packages in the repo, even those I didn't work on? +No. For incremental builds, the `rush build` command can be used to only build packages that have changes versus `rush rebuild` which always rebuilds all packages. + +> Note: It is a good idea to `rush install` after each `git pull` as dependencies may have changed. +> +### A subdirectory can not find a node_modules file or directory +If you get an error similar to the following: + +``` +[Error: ENOENT: no such file or directory, stat '/.../itwinjs-core/test-apps/display-test-app/node_modules/@bentley/react-scripts'] +``` +This means that the repo has stopped making use of an npm package that was used in the past: + +To fix this build error, you should completely remove the node_modules directory that is referenced in the error with `rush purge`, and then rerun `rush install`. + +### Updating dependencies/devDependencies on packages within the monorepo + +The version numbers of internal dependencies (see [example](https://github.com/iTwin/itwinjs-core/blob/e17654e4eca60c66bd1888f032aa03ef39d4c8a3/core/bentley/package.json#L3)) should not be manually edited. +These will be automatically updated by our internal CI pipelines. +Note that the packages are published by CI builds only. + +### Updating dependencies/devDependencies on packages external to monorepo + +Use these instructions to update dependencies and devDependencies on external packages (ones that live outside of this monorepo). + +1. Go into the appropriate `package.json` file and update the semantic version range of the dependency you want to update. +2. Run `rush check` to make sure that you are specifying consistent versions across the repository +3. Run `rush update` to make sure the newer version of the module specified in #1 is installed + + diff --git a/README.md b/README.md index b47c799cb319..3033062b2b7e 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,6 @@ This repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) that hol See [rush.json](./rush.json) for the complete list of packages and [Versioning.md](./Versioning.md) for package and API versioning policies. -Each package has its own **node_modules** directory that contains symbolic links to *common* dependencies managed by Rush. - ## Prerequisites - [Git](https://git-scm.com/) @@ -39,75 +37,6 @@ Each package has its own **node_modules** directory that contains symbolic links > See [supported platforms](./docs/learning/SupportedPlatforms.md) for further information. -## Build Instructions - -1. Clone repository (first time) with `git clone` or pull updates to the repository (subsequent times) with `git pull` -2. Install dependencies: `rush install` -3. Clean: `rush clean` -4. Build source: `rush build` -5. Run tests: `rush cover` - -The `-v` option for `rush` is short for `--verbose` which results in a more verbose command. - -The above commands iterate and perform their action against each package in the monorepo. - -If you get an error similar to the following, it means that the repo has stopped making use of an npm package that was used in the past. - -``` -[Error: ENOENT: no such file or directory, stat '/.../itwinjs-core/test-apps/display-test-app/node_modules/@bentley/react-scripts'] -``` - -To fix this build error, you should completely remove the node_modules directory that is referenced in the error with `rush purge`, and then rerun `rush install`. - -For incremental builds, the `rush build` command can be used to only build packages that have changes versus `rush rebuild` which always rebuilds all packages. - -> Note: It is a good idea to `rush install` after each `git pull` as dependencies may have changed. - -## Source Code Edit Workflow - -1. Make source code changes on a new Git branch -2. Ensure unit tests pass when run locally: `rush cover` -3. Ensure linting passes when run locally: `rush lint` -4. Locally commit changes: `git commit` (or use the Visual Studio Code user interface) -5. Repeat steps 1-4 until ready to push changes -6. Check for API signature changes: `rush extract-api`. This will update the signature files, located in `common/api`. **Note:** before doing this, first do the following: - - Be sure that your branch is up to date with the target branch (i.e. `git merge origin/master`) - - Cleanup your build output: `rush clean` - - Rebuild the project: `rush build` -7. Review any diffs to the API signature files in the `common/api` directory to ensure they are compatible with the intended release of the package. - - If any differences are in packages not modified on this branch, revert the changes before committing. -8. Add changelog entry (which could potentially cover several commits): `rush change` -9. Follow prompts to enter a change description or press ENTER if the change does not warrant a changelog entry. If multiple packages have changed, multiple sets of prompts will be presented. If the changes are only to non-published packages (like **display-test-app**), then `rush change` will indicate that a changelog entry is not needed. -10. Completing the `rush change` prompts will cause new changelog entry JSON files to be created. -11. Add and commit the changelog JSON files and any API signature updates. -12. Publish changes on the branch and open a pull request. - -> If executing scripts from `package.json` files in any of the subdirectories, we recommend using [`rushx`](https://rushjs.io/pages/commands/rushx/) over `npm`. - -If using the command line, steps 8 through 11 above can be completed in one step by running `rushchange.bat` from the imodeljs root directory. -Only use `rushchange.bat` if none of the changes require a changelog entry. -> Note: The CI build will break if changes are pushed without running `rush change` and `rush extract-api` (if the API was changed). The fix will be to complete steps 6 through 11. - -Here is a sample [changelog](https://github.com/microsoft/rushstack/blob/master/apps/rush/CHANGELOG.md) to demonstrate the level of detail expected. - -## Updating dependencies/devDependencies on packages within the monorepo - -The version numbers of internal dependencies should not be manually edited. -These will be automatically updated by the overall *version bump* workflow. -Note that the packages are published by CI builds only. - -## Updating dependencies/devDependencies on packages external to monorepo - -Use these instructions to update dependencies and devDependencies on external packages (ones that live outside of this monorepo). - -1. Edit the appropriate `package.json` file to update the semantic version range -2. Run `rush check` to make sure that you are specifying consistent versions across the repository -3. Run `rush update` to make sure the newer version of the module specified in #1 is installed - -## Other NPM Scripts - -1. Build TypeDoc documentation for all packages: `rush docs` -2. Build TypeDoc documentation for a single package: `cd core\backend` and then `rushx docs` ## Contribution From b973165bbbfaa9ffcaa2a4a063676c0ecb02bffc Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Mon, 18 Nov 2024 12:20:22 -0500 Subject: [PATCH 02/10] add quick start section with link to a sample --- README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3033062b2b7e..629fe53aaf0c 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ This repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) that hol See [rush.json](./rush.json) for the complete list of packages and [Versioning.md](./Versioning.md) for package and API versioning policies. +## Quick Start + +- This is a [sample](https://www.itwinjs.org/sandboxes/iTwinPlatform/3d%20Viewer) of an iTwin viewer - a frontend application that displays infrastructure projects on browsers. It uses many of the APIs and libraries published from this repository. +- You can also look at [other samples](https://developer.bentley.com/samples/) which showcases the capabilities of iTwin.js, and the iTwin Platform. ## Prerequisites - [Git](https://git-scm.com/) @@ -40,7 +44,17 @@ See [rush.json](./rush.json) for the complete list of packages and [Versioning.m ## Contribution -If you have questions, or wish to contribute to iTwin.js, see our [Contributing guide](./CONTRIBUTING.md). +### Build Instructions + +The following instructions will quickly set the repo up for you to edit the source code and contribute: + +1. Clone the repository locally +2. Install dependencies: `rush install` +3. Clean: `rush clean` +4. Build source: `rush build` +5. Run tests: `rush cover` + +For more information on our contributing guidelines and FAQs, see our [Contributing guide](./CONTRIBUTING.md). ## Licensing From 8c463138393fc7328dcbed6d243625c307ffd545 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Mon, 18 Nov 2024 12:24:58 -0500 Subject: [PATCH 03/10] addressing PR comments --- CONTRIBUTING.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c32aaa86401..28084559a3f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,26 +37,24 @@ Each package has its own **node_modules** directory that contains symbolic links 3. Build source: `rush build` 4. Run tests: `rush cover` -The `-v` option for `rush` is short for `--verbose` which results in a more verbose command. - The above commands iterate and perform their action against each package in the monorepo. ## Source Code Edit Workflow Once you've set up the repo, you can move on to making changes to the source code by following the steps below: -1. At the root of the repo, run `git checkout -b ""` -2. Make source code changes -3. Rebuild the repo by running `rush build` -4. Ensure unit tests pass when run locally: `rush cover` -5. Ensure linting passes when run locally: `rush lint` -6. Locally commit changes: `git commit` (or use the Visual Studio Code user interface) -7. Repeat steps 1-4 until ready to push changes +1. At the root of the repo, run `git checkout -b ""`. +2. Make source code changes. +3. Rebuild the repo by running `rush build`. +4. Ensure unit tests pass when run locally: `rush cover`. +5. Ensure linting passes when run locally: `rush lint`. +6. Locally commit changes: `git commit` (or use the Visual Studio Code user interface). +7. Repeat steps 1-4 until ready to push changes. 8. Check for API signature changes: `rush extract-api`. This will update the signature files, located in `common/api`. **Note:** before doing this, first do the following: - - Be sure that your branch is up to date with the target branch (i.e. `git merge origin/master`) - - Cleanup your build output: `rush clean` - - Rebuild the project: `rush build` + - Be sure that your branch is up to date with the target branch (i.e. `git merge origin/master`). + - Clean up your build output: `rush clean`. + - Rebuild the project: `rush build`. 9. Review any diffs to the API signature files in the `common/api` directory to ensure they are compatible with the intended release of the package. - If any differences are in packages not modified on this branch, revert the changes before committing. -10. Add changelog entry (which could potentially cover several commits): `rush change` +10. Add changelog entry (which could potentially cover several commits): `rush change`. 11. Follow prompts to enter a change description or press ENTER if the change does not warrant a changelog entry. If multiple packages have changed, multiple sets of prompts will be presented. If the changes are only to non-published packages (like **display-test-app**), then `rush change` will indicate that a changelog entry is not needed. 12. Completing the `rush change` prompts will cause new changelog entry JSON files to be created. 13. Add and commit the changelog JSON files and any API signature updates. @@ -64,9 +62,9 @@ Once you've set up the repo, you can move on to making changes to the source cod > If executing scripts from `package.json` files in any of the subdirectories, we recommend using [`rushx`](https://rushjs.io/pages/commands/rushx/) over `npm`. -If using the command line, steps 8 through 11 above can be completed in one step by running `rushchange.bat` from the imodeljs root directory. +If using the command line on Windows, steps 8 through 11 above can be completed in one step by running `rushchange.bat` from the imodeljs root directory. Only use `rushchange.bat` if none of the changes require a changelog entry. -> Note: The CI build will break if changes are pushed without running `rush change` and `rush extract-api` (if the API was changed). The fix will be to complete steps 6 through 11. +> The CI build will break if changes are pushed without running `rush change` and `rush extract-api` (if the API was changed). The fix will be to complete steps 6 through 11. Here is a sample [changelog](https://github.com/microsoft/rushstack/blob/master/apps/rush/CHANGELOG.md) to demonstrate the level of detail expected. @@ -169,7 +167,7 @@ Thank you for taking the time to contribute to open source and making great proj If your source code change only impacts the subdirectory you are working on, you can use a package manager to run local commands, without affecting other packages. -Eg. I add a new method within `core/frontend`, also adding a relevant unit test in that folder's `src/test`. I can navigate to the root of that subdirectory, and run `pnpm build`, followed by `pnpm test` or `pnpm cover`. +Eg. I add a new method within `core/frontend`, also adding a relevant unit test in that folder's `src/test`. I can navigate to the root of that subdirectory, and run `rushx build`, followed by `rushx test` or `rushx cover`. ### Do I have to rebuild all packages in the repo, even those I didn't work on? No. For incremental builds, the `rush build` command can be used to only build packages that have changes versus `rush rebuild` which always rebuilds all packages. From 781ea7fafc15b7473091f6ef46d7793e826d12f7 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Mon, 18 Nov 2024 12:26:30 -0500 Subject: [PATCH 04/10] remove more signs of 'note' --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28084559a3f2..668d5211e9b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -172,7 +172,7 @@ Eg. I add a new method within `core/frontend`, also adding a relevant unit test ### Do I have to rebuild all packages in the repo, even those I didn't work on? No. For incremental builds, the `rush build` command can be used to only build packages that have changes versus `rush rebuild` which always rebuilds all packages. -> Note: It is a good idea to `rush install` after each `git pull` as dependencies may have changed. +> It is a good idea to `rush install` after each `git pull` as dependencies may have changed. > ### A subdirectory can not find a node_modules file or directory If you get an error similar to the following: From b922b3b90fc776160090e9dcb2637807cc5478f9 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Mon, 18 Nov 2024 12:30:48 -0500 Subject: [PATCH 05/10] expanded the contribution section of our root readme --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 629fe53aaf0c..a4ca5b8b2de2 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,8 @@ The following instructions will quickly set the repo up for you to edit the sour 4. Build source: `rush build` 5. Run tests: `rush cover` -For more information on our contributing guidelines and FAQs, see our [Contributing guide](./CONTRIBUTING.md). + +For more information, our [Contributing guide](./CONTRIBUTING.md) contains detailed instructions on typical source code editing workflows, our contribution standards, FAQs, instructions on how to post questions and et cetera. ## Licensing From 7ad6261f4181d31997b9a42a7c79f853d92a8787 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Fri, 22 Nov 2024 14:30:34 -0500 Subject: [PATCH 06/10] clarify codeowners section --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 668d5211e9b5..eb948f8459ba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -157,7 +157,7 @@ We welcome contributions, large or small, including: - Example code snippets - Sample data -If you would like to contribute new APIs, please check the [CODEOWNERS](https://github.com/iTwin/itwinjs-core/blob/master/.github/CODEOWNERS) file to ensure your contributions align with the package owner's and project goals. +If you would like to contribute new APIs, create a new [discussions post](https://github.com/iTwin/itwinjs-core/discussions) and explain what these new APIs aim to accomplish. If possible check the [CODEOWNERS](https://github.com/iTwin/itwinjs-core/blob/master/.github/CODEOWNERS) file and tag the owners of the package you plan on introducing the new APIs into. Thank you for taking the time to contribute to open source and making great projects like iTwin.js possible! From cd79128b8b3314e1d9475d8135d182b922c19ce9 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Fri, 22 Nov 2024 15:20:15 -0500 Subject: [PATCH 07/10] little edit --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index a4ca5b8b2de2..fd83fd0b75ee 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ See [rush.json](./rush.json) for the complete list of packages and [Versioning.m ## Contribution -### Build Instructions +### Developer Quick Start The following instructions will quickly set the repo up for you to edit the source code and contribute: @@ -54,7 +54,6 @@ The following instructions will quickly set the repo up for you to edit the sour 4. Build source: `rush build` 5. Run tests: `rush cover` - For more information, our [Contributing guide](./CONTRIBUTING.md) contains detailed instructions on typical source code editing workflows, our contribution standards, FAQs, instructions on how to post questions and et cetera. ## Licensing From 48df965bd61a2d8f56f521f1444297d1c2f52bbc Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Tue, 26 Nov 2024 16:45:07 -0500 Subject: [PATCH 08/10] part one --- CONTRIBUTING.md | 13 ++++++++----- README.md | 7 +++---- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eb948f8459ba..3385e9a61bf3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,7 @@ The goal of this document is to provide a high-level overview of how you can get - [Writing Good Bug Reports and Feature Requests](#writing-good-bug-reports-and-feature-requests) - [Follow Your Issue](#follow-your-issue) - [Contributing Guidelines](#contributing-guidelines) + - [Branch Naming Policy](#branch-naming-policy) - [Contributor License Agreement (CLA)](#contributor-license-agreement-cla) - [Pull Requests](#pull-requests) - [Types of Contributions](#types-of-contributions) @@ -33,15 +34,14 @@ This repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) that hol Each package has its own **node_modules** directory that contains symbolic links to *common* dependencies managed by Rush. 1. Install dependencies: `rush install` -2. Clean: `rush clean` -3. Build source: `rush build` -4. Run tests: `rush cover` +2. Build source: `rush build` +3. Run tests: `rush cover` The above commands iterate and perform their action against each package in the monorepo. ## Source Code Edit Workflow Once you've set up the repo, you can move on to making changes to the source code by following the steps below: -1. At the root of the repo, run `git checkout -b ""`. +1. Create your own branch by running `git checkout -b ""`. See [Branch Naming Policy](#branch-naming-policy) 2. Make source code changes. 3. Rebuild the repo by running `rush build`. 4. Ensure unit tests pass when run locally: `rush cover`. @@ -136,6 +136,9 @@ You may be asked to clarify things or try different approaches, so please follow We'd love to accept your contributions to iTwin.js. There are just a few guidelines you need to follow. +### Branch Naming Policy + +We recommend putting your github username, followed by a succinct branch name that reflects the changes you want to make. Eg. ` git checkout -b "/cleanup-docs"` ### Contributor License Agreement (CLA) A [Contribution License Agreement with Bentley](https://gist.github.com/imodeljs-admin/9a071844d3a8d420092b5cf360e978ca) must be signed before your contributions will be accepted. Upon opening a pull request, you will be prompted to use [cla-assistant](https://cla-assistant.io/) for a one-time acceptance applicable for all Bentley projects. @@ -182,7 +185,7 @@ If you get an error similar to the following: ``` This means that the repo has stopped making use of an npm package that was used in the past: -To fix this build error, you should completely remove the node_modules directory that is referenced in the error with `rush purge`, and then rerun `rush install`. +To fix this build error, you should completely remove the node_modules directory and reinstall your dependencies. `rush update --purge` is a one-line solution for the above. ### Updating dependencies/devDependencies on packages within the monorepo diff --git a/README.md b/README.md index fd83fd0b75ee..4b12c06c7a12 100644 --- a/README.md +++ b/README.md @@ -48,11 +48,10 @@ See [rush.json](./rush.json) for the complete list of packages and [Versioning.m The following instructions will quickly set the repo up for you to edit the source code and contribute: -1. Clone the repository locally +1. Clone the repository locally: `git clone https://github.com/iTwin/itwinjs-core.git` 2. Install dependencies: `rush install` -3. Clean: `rush clean` -4. Build source: `rush build` -5. Run tests: `rush cover` +3. Build source: `rush build` +4. Run tests: `rush cover` For more information, our [Contributing guide](./CONTRIBUTING.md) contains detailed instructions on typical source code editing workflows, our contribution standards, FAQs, instructions on how to post questions and et cetera. From b06d1dac1557a72885a9fbb195b24a3cb23ba2f4 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Wed, 27 Nov 2024 13:26:52 -0500 Subject: [PATCH 09/10] address comments --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3385e9a61bf3..8bec8bcc3d5a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ The goal of this document is to provide a high-level overview of how you can get ## Repo Setup -This repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) that holds the source code to multiple iTwin.js npm packages. It is built using [Rush](http://rushjs.io/). +This repository is a [monorepo](https://monorepo.tools/) that holds the source code for multiple [iTwin.js npm packages](https://www.npmjs.com/search?q=%40itwin). It is built using [Rush](http://rushjs.io/). Each package has its own **node_modules** directory that contains symbolic links to *common* dependencies managed by Rush. @@ -160,7 +160,7 @@ We welcome contributions, large or small, including: - Example code snippets - Sample data -If you would like to contribute new APIs, create a new [discussions post](https://github.com/iTwin/itwinjs-core/discussions) and explain what these new APIs aim to accomplish. If possible check the [CODEOWNERS](https://github.com/iTwin/itwinjs-core/blob/master/.github/CODEOWNERS) file and tag the owners of the package you plan on introducing the new APIs into. +If you would like to contribute new APIs, create a new [issue](https://github.com/iTwin/itwinjs-core/issues) and explain what these new APIs aim to accomplish. If possible check the [CODEOWNERS](https://github.com/iTwin/itwinjs-core/blob/master/.github/CODEOWNERS) file and tag the owners of the package you plan on introducing the new APIs into. Thank you for taking the time to contribute to open source and making great projects like iTwin.js possible! From e731c117bb1e42c55d7be7b74967a7ea253410f3 Mon Sep 17 00:00:00 2001 From: Nam Le <50554904+hl662@users.noreply.github.com> Date: Sat, 30 Nov 2024 15:38:57 +0900 Subject: [PATCH 10/10] move source code edit workflow steps in an collapsible block --- CONTRIBUTING.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8bec8bcc3d5a..728dfc187adb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,10 @@ Each package has its own **node_modules** directory that contains symbolic links The above commands iterate and perform their action against each package in the monorepo. ## Source Code Edit Workflow -Once you've set up the repo, you can move on to making changes to the source code by following the steps below: + +
+ Once you've set up the repo, you can move on to making changes to the source code by following the steps within: + 1. Create your own branch by running `git checkout -b ""`. See [Branch Naming Policy](#branch-naming-policy) 2. Make source code changes. 3. Rebuild the repo by running `rush build`. @@ -68,6 +71,8 @@ Only use `rushchange.bat` if none of the changes require a changelog entry. Here is a sample [changelog](https://github.com/microsoft/rushstack/blob/master/apps/rush/CHANGELOG.md) to demonstrate the level of detail expected. +
+ ### Other NPM Scripts 1. Build TypeDoc documentation for all packages: `rush docs`