Skip to content

Latest commit

 

History

History
97 lines (65 loc) · 5.13 KB

6. submitting-a-pr.md

File metadata and controls

97 lines (65 loc) · 5.13 KB
Raw

Contribution Guide

  1. Getting Set up
  2. Building Samples and Packages
  3. Running a Sample or Storybook
  4. Testing your changes
  5. Writing unit tests
  6. Submitting a PR
  7. Having your changes published

6. Submitting a PR

Prerequisites to publishing a Pull Request

Once you have gotten setup with the repo, made and tested your changes, there are some checks before submitting your PR:

  1. Update dependencies lock file
  2. Update package API files
  3. Generate required change files

1. Update dependencies lock file for all flavors

If you are adding/updating dependencies in any package.json file, you will need to update dependencies lock files for both beta and stable flavors before submitting changes, run these commands to ensure they are correctly generated:

For beta:

rush update

For stable:

rush update:stable

These commands will update your dependencies locally and update the pnpm-lock.yaml. You may wish to install the correct dependencies for your current flavor (by default, run rush switch-flavor:beta again for switching back to beta flavor).

2. Update package API files

To ensure we do not break any existing public APIs, we use api-extractor across all our npm packages. This generates a file detailing all public exports of the package. You can find this file under package-root/review/beta/package-name.api.md. We do this to prevent any accidental breaking changes to the packages we export, and to ensure we do not accidentally publish any internal helper classes/functions.

When a package is built the api-extractor is automatically run and will update the corresponding api.md file.

  • If you are updating APIs under stable version, it is necessary to update the api.md for both beta and stable versions. A quick command to do so is rush build:all-flavors, which will build under all flavors and generate API files for both. Alternatively, you can switch to the stable flavor by running rush switch-flavor:stable and perform the step below to generate stable api.md (don't forget to run rush switch-flavor:beta when finished if necessary).

To ensure these API files have been updated, run rush build -t @azure/communication-react to have all packages update their API files. Then submit any changed api.md files along with your PR.

3. Generate a change file to describe your changes

To ensure we have high-quality changelogs when new versions are released, and make sure your contribution does not go unaccredited for, we ask you to create a change file to describe your changes. To generate the change file first make sure all your changes are committed, then run:

rush changelog

This will start an interactive tool, See Changelog Guidelines for more information on how to use this tool.

Generating new snapshots for your UI changes

If you are making a UI change in your PR, you might invalidate some screen snapshots in our automated visual tests.

  1. Check the failing Github Actions to see if the failure is due to a UI change.

    screenshot showing downloadable snapshot artifacts in a failed github action

  2. Add the update_snapshot label to the PR.

  3. Wait for Github Actions to generate new snapshots for the PR.

  4. The validation pipelines will be re-run after new snapshots are generated.

For more details on UI tests and debugging failed UI tests, see Automated tests.

Whenever you see the breaking change failure

It means you have a technical breaking change - in most cases, this means you have a real breaking change, so please check whether your PRs are modifying APIs in a way that is incompatible with the current published API. There are exemptions because our definition of breaking change is a bit different from technical breaking change: If you are adding properties/functions directly to:

  1. All state,
  2. All adapters
  3. All stateful clients,

These aren't considered as breaking changes, and if this is the case, please add the breaking-change tag to your PR. Note: Changing names of functions or properties or making existing functions/properties incompatible is still a breaking change; please do not check in these changes.

Submitting your PR

You're ready to submit your PR! 🚀 Thank you for your contribution!

Once you have submitted your PR it must pass several automated checks that help keep our packages and repo healthy:

  • ✅ At least two reviewers must approve the changes
  • ✅ All packages, samples, and storybook must build successfully
  • ✅ Unit tests must all pass
  • ✅ Linting must succeed without warnings
  • ✅ Appropriate change files must be included
  • ✅ Check for public API regressions must not fail