Skip to content

Latest commit

 

History

History
126 lines (92 loc) · 6.53 KB

CONTRIBUTING.md

File metadata and controls

126 lines (92 loc) · 6.53 KB
Raw

Contributing Guidelines

Thank you for your interest in contributing to our project! 💛

Please read through these guidelines carefully before submitting a PR and let us know if it's not up to date (or even better, submit a PR with your corrections 😉).

Table of Contents

Bug Reports

Bug reports and feature requests are always welcome. Good bug reports are extremely helpful, so thanks in advance!

When filing a bug, please try to be as detailed as possible. In addition to the bug report form information, details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The date/commit/version(s) of the code you're running
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Guidelines for bug reports:

  • Check to see if a duplicate or closed issue already exists!
  • Provide a short and descriptive issue title
  • Remove any sensitive data from your examples or snippets
  • Format any code snippets using Markdown syntax

Finally, thank you for taking the time to read this, and taking the time to write a good bug report.

Pull Requests

We welcome pull requests!

You should open an issue to discuss your pull request, unless it's a trivial change. It's best to ensure that your proposed change would be accepted so that you don't waste your own time. If you would like to implement support for a significant feature that is not yet available, please talk to us beforehand to avoid any duplication of effort.

Contribution Process

  1. Fork & Clone this repo (Make sure to disable associated GitHub Actions. In fork go to Settings > Actions > General > Disable actions > save)
  2. nvm install
  3. nvm use
  4. yarn setup
  5. Within your fork, create a new branch based on the issue you're addressing, e.g. git checkout -b angular/remove-browser-module
  6. Commit your code using conventional commit messages, e.g. git commit -m "chore: remove browser module".
  7. Once your work is committed, validate your changes according to local development guides.
  8. If this is a change to any customer-facing aspect of a component, for example a new prop, feature, or a breaking change, update or add relevant documentation. If this is a large change, documentation updates can be made in a separate PR, but should be noted as a followup in the PR description. See the specific contributing guide for documentation here
  9. Push your branch with git push origin -u
  10. Open a PR against this repo from your newly published branch.
  11. Add a changeset that describes your changes. More info here. Please make sure that your changeset only bumps @aws-amplify/* packages and does not bump any of private packages like docs, e2e, examples, etc. If you only updated a private package like docs, e2e, or examples, skip this step.
  12. Finally, Amplify UI team will review your PR. Add reviewers based on the core member who is tracking the issue with you or code owners. In the meantime, address any automated check that fail (such as linting, unit tests, etc. in CI)

Troubleshooting

Apple Silicon: If using an M1 (or more recent) Macbook and you get the following error message regarding installation of canvas:

error /Users/USERNAME/amplify-ui/node_modules/canvas: Command failed.
Exit code: 1
...
/bin/sh: pkg-config: command not found
gyp: Call to 'pkg-config pixman-1 --libs' returned exit status 127 while in binding.gyp. while trying to load binding.gyp`

See the canvas docs to install required dependencies for local docs development.

Python >= 3.12: If you are using Python 3.12 or greater and you get the following error message regarding installation of canvas:

error /Users/USERNAME/amplify-ui/node_modules/canvas: Command failed.
Exit code: 1
...
ModuleNotFoundError: No module named 'distutils'

See the setuptools installation website. Setuptools serves as a recommended alternative to distutils.

Project Structure

amplify-ui is a monorepo that contains the following workspaces:

amplify-ui
├── canary # contains examples we use to test build systems
├── docs # ui.docs.amplify.aws documentation code
├── environments # Amplify backend environments we use for e2e testing
├── examples # Example apps we use for e2e testing
│   └── angular
│   └── next
│   └── vue
├── packages # Amplify UI components implementations
│   └── angular
│   └── react
│   └── vue

Local Development Guides

Please refer to the following contributing guides:

Publishing

Amplify UI publishes to NPM on every Tuesday. We use changesets to drive our deployment procedure:

  1. Each contributor adds a changeset in their PR
  2. Changesets get accumulated into Version Packages PR.
  3. Maintainer will run tests, approve, and merge the PR.
  4. Previous step will trigger publish-latest action that will build and publish packages to NPM.

Docs Publishing

Amplify UI publishes updates to the UI docs site each Tuesday as a part of the primary publish process. For Pull Requests that require publishing outside of the standard publish process, a one week lead time is required with the exception of high severity issues.