Thank you for your interest in contributing! There are several ways you can help.
Please take a read through this document to help streamline the process of getting your contributions added.
Tooling to assist with development of component libraries within the monorepo.
This monorepo is using Rush.js tooling.
rush update: This command should be run after a git checkout (or a git pull) and after adding or removing a dependency to a package, if you remove a dependency, use --recheck flag so that dependency get removed from the lock files. This will download and update your packages (akin npm install)
rush build: This command should be run after a rush update. This will build the packages for which change have been detected, rush rebuild will do the same, but with all packages, regardless of change detection.
rush change: This command should be run before creating a pull request, it will ask changes questions for published packages, and create a CHANGELOG.md out of the answers.
rush test: This command should be run before a git commit, it will run all tests for the full repository.
rush clean: This command is available to delete all build artifacts. Each package should define the script to meet their own needs.
Storybook is a tool that will allow developing components without having to create a separate test application. Some addons are included to facilitate access token management and project selection, for example.
Storybook is using an addon that is built locally, so you will need to have run rush build at least once before starting storybook.
It also requires an OIDC client id registered for SPA use of Bentley API's. This client will require scopes that may evolve over time. The current storybook configuration should show which are required at the moment. (Look for authClientConfig:scope in the parameters json object). The client should have the http://localhost:6006/signin-oidc.html redirect url.
Once you have a client id, you should set the value of the STORYBOOK_AUTH_CLIENT_ID environment variable to your client id. One approach to accomplish this would be to add a packages/apps/storybook/.env.local file and add STORYBOOK_AUTH_CLIENT_ID=yourClientId to the file.
You can start storybook by running the following commands:
cd packages/apps/storybook
rushx start
Note: In order for the storybook documentation to be created automatically out of your code, you will need to declare the component used in the story within storybook, this story gives details on the required steps.
If your component uses accessToken as a prop, you can wrap your story with the withAccessTokenOverride HOC, which will use the token from the toolbar add-on instead of what a user could enter in the "Control" section. See this story for a usage example.
Similarly, if your component uses projectId as a prop, you can wrap your story with the withProjectIdOverride HOC, which will take the projectId from the toolbar add-on. This add-on will only show if the active story has a projectId prop and the user is authenticated. The projects that will be available in the toolbar are the authenticated user's Favorite Projects in CONNECT QA. To fill the list, you would need to go to CONNECT and toggle favorite for some projects. Note that if you enter a value for projectId in the storybook Control panel, the add-on will not override this value. See this story for a usage example.
A Project is defined as a self-contained piece of functionality. Each new project is in a sub-folder of the ./packages folder in this repository. The name of the folder should share a similar name of the package that will be published and should contain the source code for that project.
Because each Project is self-contained, it is necessary for the contributor of the Project to specify a contact for PRs and bug reports. To do this, add an entry to the CODEOWNERS file in the root directory of the repository, e.g.:
# Clara Developer owns the new extension snippet
/packages/imodel-select @clara.developer
Remember that the last entry for a matching directory or file name pattern takes precedence over any earlier entries.
Update the ./README.md and ./rush.json files with the package you are adding.
- All names should be hyphenated lower case (e.g., imodel-select).
Have you identified a reproducible problem in this code? Have a feature requests? Please create an Issue, but first make sure that you search the work items to make sure that it has not been entered yet. If you find your issue already exists, please add relevant comments or just a thumbs up to let us know that more people face this issue.
File a single issue per problem and feature request. Do not enumerate multiple bugs or feature requests in the same issue.
Do not add your issue as a comment to an existing issue unless it's for the identical input. Many issues look similar, but have different causes.
The more information you can provide, the more likely someone will be successful at reproducing the issue and finding a fix.
Please include the following with each issue:
- Version of the package
- Your operating system
- Reproducible steps (1... 2... 3...) that cause the issue
- What you expected to see, versus what you actually saw
- Images, animations, or a link to a video showing the issue occurring
- A code snippet that demonstrates the issue or a link to a code repository the developers can easily pull down to recreate the issue locally
We follow the normal GitHub pull request workflow to ensure that all code changes in this repository are code reviewed and all tests pass. This means that there will be a number of reviewers that formally review and sign off for changes. Reviewers should check for redundancy, optimization, stylization, and standardization in each changeset. While we will try to keep this repository as collaborative and open-source as possible, it must also be reliable.
Every change must be tested with proper unit tests. Integration tests are highly encouraged in libraries with critical workflows to ensure end-to-end consistency.
Every change must be described with a change log: Run "rush change" on your committed and always choose "patch" as the change type. Commit your change log along with your pull request.
- Get latest change from "main":
git checkout mainandgit pull - Install all required packages locally:
rush update - Build all modules, (required for storybook to work correctly):
rush build - Make a new Git branch:
git checkout -b [mybranch] - Make source code changes.
- Remember that you can use storybook as a running environment for your package.
- Ensure unit tests pass when run locally:
rush test. - Commit your changes.
- Add a changelog entry (which could potentially cover several commits):
rush change -b origin/main. - 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.
- Completing the
rush changeprompts will cause a new changelog entry JSON files to be created. - Commit the changelog JSON files.
- Publish changes to the branch and open a pull request:
git push [mybranch] -u origin/[mybranch]