From 05392fed4b15a5400c52617ec3b7cb9b789bc65e Mon Sep 17 00:00:00 2001 From: William Lee <43682783+wlee221@users.noreply.github.com> Date: Wed, 9 Feb 2022 12:45:47 -0800 Subject: [PATCH] Update `CONTRIBUTING.md` (#1264) * First draft * Reorder items and add publishing readme * Fix heading * grammar :p * Wording * Fix #pull-request link * Add canary folder description * Update changeset desc --- CONTRIBUTING.md | 202 +++++++++++-------------------- docs/README.md | 35 +----- examples/README.md | 15 +++ package.json | 1 + packages/angular/CONTRIBUTING.md | 50 ++++++++ packages/e2e/README.md | 76 +++++++++++- packages/react/CONTRIBUTING.md | 17 +++ packages/ui/CONTRIBUTING.md | 7 ++ packages/ui/README.md | 2 +- packages/vue/CONTRIBUTING.md | 17 +++ 10 files changed, 254 insertions(+), 168 deletions(-) create mode 100644 examples/README.md create mode 100644 packages/angular/CONTRIBUTING.md create mode 100644 packages/react/CONTRIBUTING.md create mode 100644 packages/ui/CONTRIBUTING.md create mode 100644 packages/vue/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb08301ad88..ca58f3f3658 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,135 +1,97 @@ -# Contributing +# Contributing Guidelines -## Getting Started +Thank you for your interest in contributing to our project! πŸ’› -1. Fork & Clone this repo -1. [`nvm install`](https://github.com/nvm-sh/nvm) -1. [`nvm use`](https://github.com/nvm-sh/nvm) -1. `yarn install` -1. `yarn build` - -## Documentation Development - -1. Run the documentation via `yarn docs dev` -1. Visit -1. Create/Update content based on the URL. - - For example, the content for - http://localhost:5000/components/authenticator is located at [`docs/src/pages/components/authenticator/index.mdx`](docs/src/pages/components/authenticator/index.mdx) - -Internally, this content is served by a single, Next.js [optional catch all route](https://nextjs.org/docs/routing/dynamic-routes#optional-catch-all-routes): -[`docs/src/pages/[[...slugs]].tsx`](docs/src/pages/[[...slugs]].tsx). - -## `@aws-amplify/ui` - -- `yarn ui build` to rebuild for production. -- `yarn ui dev` to watch & rebuild for development. - -## `@aws-amplify/ui-react` - -- `yarn react build` to rebuild for production. -- `yarn react dev` to watch & rebuild for development. -- `yarn next-example dev` to run React examples on Next.js. - -## `@aws-amplify/ui-vue` - -- `yarn vue build` to rebuild for production -- `yarn vue dev` to watch & rebuild for development. -- `yarn vue-example dev` to run Vue examples on Vite. - -## `@aws-amplify/ui-angular` - -- `yarn angular build` to rebuild for production -- `yarn angular dev` to watch & rebuild for development -- `yarn angular-example dev` to run Angular examples. - -### Angular Troubleshooting +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 πŸ˜‰). -Whenever `yarn angular build` is run, such as part of postinstall script, you want to run `yarn angular dev` again. This is to ensure that both `yarn angular` and `yarn angular-example` have [ivy](https://angular.io/guide/ivy) enabled for local development. +## Table of Contents -## Examples Development +- [Bug Reports](#bug-reports) +- [Pull Requests](#pull-requests) +- [Project Structure](#project-structure) +- [Local Development Guides](#local-devleopment-guides) +- [Publishing](#publishing) +- [Updating Icons](#updating-icons) -1. Create or Update an example at [`examples/{next,vue,angular}/...`](examples) - - For your `aws-exports.js`, you can [reference an existing or create a new environment](environments). - - ```js - // examples/next/pages/components/authenticator/sign-up-with-username.tsx - import { Authenticator } from '@aws-amplify/ui-react'; - import { Amplify } from 'aws-amplify'; - import awsExports from '../../../../../environments/auth-with-username-no-attributes/src/aws-exports'; - - Amplify.configure(awsExports); - - export default function AuthenticatorWithUsername() { - return ; - } - ``` - -1. Run your example: `yarn {next,vue,angular}-example dev` -1. Visit your example (e.g. ) -1. Make changes to [`@aws-amplify/ui-{react,vue,angular}`](packages) & save. - - Examples should automatically hot-reload your changes in the example. - -### E2E Testing - -1. Create or Update a `${feature}.feature` file (using [Gherkin](https://cucumber.io/docs/gherkin/reference/)) describing the behavior in [`packages/e2e/features/${slug}`](packages/e2e/features). +## Bug Reports - ```gherkin - Feature: My new feature +Bug reports and feature requests are always welcome. Good bug reports are extremely helpful, so thanks in advance! - Documentation-friendly description of this feature, why it exists, & how to use it. +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: - @angular @react @vue - Scenario: Example scenario using this feature - Given some "STARTING_POINT" - When I DO "SOMETHING" - And I DO SOMETHING "ELSE" - Then I see "THE DESIRED BEHAVIOR" +- 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 - @react @skip - Scenario: Some React-specific scenario that can't be rain in CI +Guidelines for bug reports: - @angular @todo-react @todo-vue - Scenario: Some scenario supported in Angular, but React & Vue haven't added yet - ``` +- Check to see if a [duplicate or closed issue](https://github.com/aws-amplify/amplify-ui/issues?q=is%3Aissue+) already exists! +- Provide a short and descriptive issue title +- Remove any sensitive data from your examples or snippets +- Format any code snippets using [Markdown](https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks) syntax -1. Create or Update the accompanying `${slug}.feature` tests (e.g. `packages/e2e/cypress/integration/${slug}/${feature}/${feature}.steps.ts` -1. Start one of the [examples](examples). -1. Run `yarn e2e dev` to load Cypress +Finally, thank you for taking the time to read this, and taking the time to write a good bug report. - ```shell - TAGS='@react and not (@skip or @todo-react)' yarn e2e dev - ``` +## Pull Requests -1. Click on your updated `${feature}.feature` file to validate your changes -1. Add tags above your `Scenario` to indicate how this feature should be tested: +We welcome pull requests! - - If the library supports it, then add one of the following: +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. - - `@angular` for `@aws-amplify/ui-angular` - - `@react` for `@aws-amplify/ui-react` - - `@vue` for `@aws-amplify/ui-vue` +### Contribution Process - This will ensure automated documentation marks these as supported features. +1. Fork & Clone this repo +1. [`nvm install`](https://github.com/nvm-sh/nvm) +1. [`nvm use`](https://github.com/nvm-sh/nvm) +1. `yarn setup` +1. Within your fork, create a new branch based on the issue you're addressing -- `git checkout -b angular/remove-browser-module` +1. Once your work is committed, validate your changes according to [local development guides](#local-devleopment-guides). +1. Push your branch with `git push origin -u` +1. Open a PR against this repo from your newly published branch. +1. Add a [changeset](https://github.com/changesets/changesets) that describes your changes. More info [here](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md). Please make sure that your changeset only bumps `@aws-amplify/*` packages and does not bump any of private packages like `docs`, `e2e`, `examples`, etc. +1. 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) + +## Project Structure + +`amplify-ui` is a monorepo that contains the following workspaces: + +```bash +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 +``` - - If the library supports it, **but tests cannot be ran in CI for technical reasons**, then also add: +## Local Devleopment Guides - - `@skip` for all libraries - - `@skip-angular` for specifically `@aws-amplify/ui-angular` - - `@skip-react` for specifically `@aws-amplify/ui-react` - - `@skip-vue` for specifically `@aws-amplify/ui-vue` +Please refer to the following contributing guides: - This will ensure automated documentation marks these as supported features, but won't block builds (in PRs or `main`) with test failures. +- [`docs`](docs/README.md#contributing) +- [`@aws-amplify/ui`](packages/ui/CONTRIBUTING.md) +- [`@aws-amplify/ui-angular`](packages/angular/CONTRIBUTING.md) +- [`@aws-amplify/ui-react`](packages/react/CONTRIBUTING.md) +- [`@aws-amplify/ui-vue`](packages/vue/CONTRIBUTING.md) +- [`examples`](examples/README.md#examples-development) +- [`e2e`](packages/e2e/README.md#contributing) +- [`environments`](environments/README.md#external-contributors) - - If the library _should_ support it, then also add: +## Publishing - - `@todo-angular` for `@aws-amplify/ui-angular` - - `@todo-react` for `@aws-amplify/ui-react` - - `@todo-vue` for `@aws-amplify/ui-vue` +Amplify UI team publishes to NPM on every Tues (mandatory) and Thurs (optional). We use [`changesets`](https://github.com/changesets/changesets) to drive our deployment procedure: - This will ensure automated documentation marks these as _upcoming_ features, will skip these on PRs, but **will error on `main` until completed**. +1. Each contributor adds a changeset in their PR +1. Changesets get accumulated into [Version Packages PR](https://github.com/aws-amplify/amplify-ui/pulls/app%2Fgithub-actions). +1. Maintainer will run tests, approve, and merge the PR. +1. Previous step will trigger [`publish-latest`](./.github/workflows/publish-next.yml) action that will build and publish packages to NPM. ## Updating Icons @@ -144,23 +106,3 @@ yarn build:icons 1. Review and commit changes to icons 1. Submit PR for review - -## 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](https://github.com/aws-amplify/amplify-ui/issues?q=is%3Aissue+) already exists! -- Provide a short and descriptive issue title -- Remove any sensitive data from your examples or snippets -- Format any code snippets using [Markdown](https://docs.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks) syntax - -Finally, thank you for taking the time to read this, and taking the time to write a good bug report. diff --git a/docs/README.md b/docs/README.md index 2c1c053f1e9..7b51721b5a8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,45 +2,18 @@ These docs are published at https://docs.amplify.aws/ui and powered by the following technologies: -- [aws-amplify/docs#next](https://github.com/aws-amplify/docs/tree/next) – Layout & Styling - - Before updating, `yarn` v1 has a known bug where cached GitHub tarballs aren't updated. Explicitly clear any previously cached versions of `amplify-docs`: - - ```shell - # /Users/user/Library/Caches/Yarn/v6/npm-amplify-docs-* - rm -rf $(yarn cache dir)/npm-amplify-docs-* - # Remove all node_modules, otherwise yarn won't install the new version - rm -rf node_modules - ``` - - As a GitHub dependency, this package should be **explicitly updated** using a SHA (e.g. `#33d383d`) rather than a branch (e.g. `#next`): - - ```shell - yarn docs add amplify-docs@github:https://github.com/aws-amplify/docs#33d383d - ``` - - You can find the latest/relevant commit at https://github.com/aws-amplify/docs/commits/next. - - Finally, if you make any changes to `node_modules/amplify-docs`, you can save these using `patch-package`: - - ```shell - npx patch-package amplify-docs - ``` - - [XDM](https://github.com/wooorm/xdm) – Content - [Next.js](https://nextjs.org/) – Framework -## Getting Started +## Contributing + +### Getting Started 1. Navigate to the _root_ of your local clone of [aws-amplify/amplify-ui](https://github.com/aws-amplify/amplify-ui) -1. Run `yarn install` +1. Run `yarn setup` 1. Run `yarn docs dev` 1. Open - (The docs root is `/ui` for consistency with https://docs.amplify.aws/ui) - -## Contributing - ### Creating a Page Page paths mirror their URLs. For example, `/ui/components/authenticator` is located at [/src/pages/ui/components/authenticator/index.page.mdx](src/pages/ui/components/authenticator/index.page.mdx). diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000000..fb6c78a4a76 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,15 @@ +# Examples + +This directory contains example apps for each framework we support. + +## Examples Development + +1. Create or Update an example at [`examples/{next,vue,angular}/...`](examples) + + For your `aws-exports.js`, you can [reference an existing or create a new environment](environments). + +1. Run your example at monorep root: `yarn {next,vue,angular}-example dev` +1. Visit your example (e.g. ) +1. Make changes to [`@aws-amplify/ui-{react,vue,angular}`](packages) & save. + + Examples should automatically hot-reload your changes in the example. diff --git a/package.json b/package.json index 9d544881737..0701444df45 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "angular-example": "yarn workspace angular-example", "docs": "yarn workspace docs", "next-example": "yarn workspace next-example", + "react-example": "yarn workspace next-example", "vue-example": "yarn workspace vue-example", "e2e": "yarn workspace e2e", "environments": "yarn workspace environments", diff --git a/packages/angular/CONTRIBUTING.md b/packages/angular/CONTRIBUTING.md new file mode 100644 index 00000000000..b6d5a11dd40 --- /dev/null +++ b/packages/angular/CONTRIBUTING.md @@ -0,0 +1,50 @@ +# Contributing + +## Development Structure + +`@aws-amplify/ui-angular` utilizes a monorepo structure to manage devDependencies and the actual packages separately. + +This directory (`packages/angular`) contains base dependencies for developing angular packages. The actual code for `@aws-amplify/ui-angular` is located in [`projects/ui-angular`](./projects/ui-angular/) directory. + +```bash +packages/angular/ +β”œβ”€β”€ projects/ui-angular/ # where the actual `@aws-amplify/ui-angular` library lives +β”‚ β”œβ”€β”€ src/ # contains src files for UI library code. +β”‚ β”œβ”€β”€ legacy/ # contains re-expors of legacy web components +β”‚ β”‚ └── src/ +β”‚ β”‚ └── package.json # required by ng-packagr to setup secondary entry points +β”‚ └── package.json # name: `@aws-amplify/ui-angular`, private: false +β”‚ # contains dependencies that library needs (e.g. xstate) +β”‚ +β”œβ”€β”€ dist/ui-angular/ # this is auto-generated on build. Deployments will only happen from this folder. +β”‚ └── esm2015/ +β”‚ └── fesm2015/ +β”‚ └── lib/ +β”‚ └── package.json # same as the above, but defines extra fields like +β”‚ # main, module, esm2015, typings, sideEffects. +β”‚ +└── package.json # name: 'amplify-ui-angular-mono`, private: true + # contains base dependencies for developing angular packages. + # This is only for infrastructure purpose! Shouldn't be + # published or be referenced by other dependencies. +``` + +## Getting Started + +1. Navigate to the _root_ of your local clone of [aws-amplify/amplify-ui](https://github.com/aws-amplify/amplify-ui) +1. Run `yarn setup` +1. Run `yarn angular dev` + +This will start building `@aws-amplify/ui-angular` in watch mode. To test your changes, you can utilize [`examples/angular`](../../examples/angular) to run examples on Angular. Please see examples [README](../../examples/README.md) and e2e [README](../e2e/README.md#contributing) to get started. + +### Depenencies + +`@aws-amplify/ui-react` depends on [`@aws-amplify/ui`](../ui) for theming, state management, and translation logic. If you're looking for change in these, please refer to `@aws-amplify/ui` [README](../ui/README.md). + +## Testing for Production + +After you tested your change, you can run `yarn angular build` and `yarn angular-example build` from monorepo to run build for production. + +## Troubleshooting + +If you're cross developing `angular` and `angular-example`, make sure you're running the same type of commands -- either run `yarn angular dev` and `yarn angular-example dev` together, or run `yarn angular build` and `yarn angular-example build` together. Not doing so will result in IVY compiler conflict. diff --git a/packages/e2e/README.md b/packages/e2e/README.md index 11e25556f57..2d42749300f 100644 --- a/packages/e2e/README.md +++ b/packages/e2e/README.md @@ -2,14 +2,78 @@ # Testing E2E with Cypress +## Getting Started + +To run existing tests on your desired `framework`: + +_prerequisite_: You must create populate `packages/e2e/.env` values in order for tests to run successfully against the examples. The values you need to populate are specified in [`packages/e2e/.env.example`](./.env.example). Please see [Creating test users](#creating-test-users) to see our conventions. + +1. Navigate to the _root_ of your local clone of [aws-amplify/amplify-ui](https://github.com/aws-amplify/amplify-ui) +1. Run `yarn setup` +1. Run `yarn [framework] dev` (e.g. `yarn react build`) +1. Run `yarn [framework]-example dev` (e.g. `yarn react-example dev`) +1. Run `yarn e2e dev` + +## Contributing + ### Making new tests -- Make a new `.feature` file in `./features/your/feature/path/` - - You can follow the example of one of the other existing `.feature` files -- Navigate to `./cypress/integration/your/feature/path/` and create a new folder following the naming convention of the `.feature` you made, and inside that folder, make a `.steps.ts` file with the same name. Then, write your Cypress tests in that file. -- Make sure you have the `examples/next` app running on `localhost:3000`, as Cypress will look to that port to test against -- From this project directory, run `yarn dev` to open Cypress. Then, choose which test to run in the UI. -- Cypress will automatically re-run tests every time you make an edit to the test file. +1. Create or Update a `${feature}.feature` file (using [Gherkin](https://cucumber.io/docs/gherkin/reference/)) describing the behavior in [`packages/e2e/features/${slug}`](packages/e2e/features). + + ```gherkin + Feature: My new feature + + Documentation-friendly description of this feature, why it exists, & how to use it. + + @angular @react @vue + Scenario: Example scenario using this feature + Given some "STARTING_POINT" + When I DO "SOMETHING" + And I DO SOMETHING "ELSE" + Then I see "THE DESIRED BEHAVIOR" + + @react @skip + Scenario: Some React-specific scenario that can't be rain in CI + + @angular @todo-react @todo-vue + Scenario: Some scenario supported in Angular, but React & Vue haven't added yet + ``` + +1. Create or Update the accompanying `${slug}.feature` tests (e.g. `packages/e2e/cypress/integration/${slug}/${feature}/${feature}.steps.ts` +1. Start one of the [examples](examples). +1. Run `yarn e2e dev` to load Cypress + + ```shell + TAGS='@react and not (@skip or @todo-react)' yarn e2e dev + ``` + +1. Click on your updated `${feature}.feature` file to validate your changes +1. Add tags above your `Scenario` to indicate how this feature should be tested: + + - If the library supports it, then add one of the following: + + - `@angular` for `@aws-amplify/ui-angular` + - `@react` for `@aws-amplify/ui-react` + - `@vue` for `@aws-amplify/ui-vue` + + This will ensure automated documentation marks these as supported features. + + - If the library supports it, **but tests cannot be ran in CI for technical reasons**, then also add: + + - `@skip` for all libraries + - `@skip-angular` for specifically `@aws-amplify/ui-angular` + - `@skip-react` for specifically `@aws-amplify/ui-react` + - `@skip-vue` for specifically `@aws-amplify/ui-vue` + + This will ensure automated documentation marks these as supported features, but won't block builds (in PRs or `main`) with test failures. + + - If the library _should_ support it, then also add: + + - `@todo-angular` for `@aws-amplify/ui-angular` + - `@todo-react` for `@aws-amplify/ui-react` + - `@todo-vue` for `@aws-amplify/ui-vue` + + This will ensure automated documentation marks these as _upcoming_ features, will skip these on PRs, but **will error on `main` until completed**. ### Creating test users diff --git a/packages/react/CONTRIBUTING.md b/packages/react/CONTRIBUTING.md new file mode 100644 index 00000000000..55690c27f91 --- /dev/null +++ b/packages/react/CONTRIBUTING.md @@ -0,0 +1,17 @@ +# Contributing + +## Getting Started + +1. Navigate to the _root_ of your local clone of [aws-amplify/amplify-ui](https://github.com/aws-amplify/amplify-ui) +1. Run `yarn setup` +1. Run `yarn react dev` + +This will start building `@aws-amplify/ui-react` in watch mode. To test your changes, you can utilize [`examples/next`](../../examples/next) to run examples on `next.js`. Please see examples [README](../../examples/README.md) and e2e [README](../e2e/README.md#contributing) to get started. + +## Depenencies + +`@aws-amplify/ui-react` depends on [`@aws-amplify/ui`](../ui) for theming, state management, and translation logic. If you're looking for change in these, please refer to `@aws-amplify/ui` [README](../ui/README.md). + +## Testing for Production + +After you tested your change, you can run `yarn react build` from monorepo to run build for production. diff --git a/packages/ui/CONTRIBUTING.md b/packages/ui/CONTRIBUTING.md new file mode 100644 index 00000000000..94199e980c5 --- /dev/null +++ b/packages/ui/CONTRIBUTING.md @@ -0,0 +1,7 @@ +# Contributing + +## Getting started + +1. Navigate to the _root_ of your local clone of [aws-amplify/amplify-ui](https://github.com/aws-amplify/amplify-ui) +1. Run `yarn setup` +1. Run `yarn ui dev` diff --git a/packages/ui/README.md b/packages/ui/README.md index 61f4a3709d9..6eb12abe86e 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -1,6 +1,6 @@ # Amplify UI (Core) -> Low-level logic & styles for stand-alone usage or re-use in framework-specific implementations. +`@aws-amplify/ui` contains low-level logic & styles for stand-alone usage or re-use in framework-specific implementations. - [Theme](src/theme) - [I18n](src/i18n) diff --git a/packages/vue/CONTRIBUTING.md b/packages/vue/CONTRIBUTING.md new file mode 100644 index 00000000000..b857e76aeb3 --- /dev/null +++ b/packages/vue/CONTRIBUTING.md @@ -0,0 +1,17 @@ +# Contributing + +## Getting Started + +1. Navigate to the _root_ of your local clone of [aws-amplify/amplify-ui](https://github.com/aws-amplify/amplify-ui) +1. Run `yarn setup` +1. Run `yarn vue dev` + +This will start building `@aws-amplify/ui-vue` in watch mode. To test your changes, you can utilize [`examples/vue`](../../examples/next) to run examples on `vite`. Please see examples [README](../../examples/README.md) and e2e [README](../e2e/README.md#contributing) to get started. + +## Depenencies + +`@aws-amplify/ui-vue` depends on [`@aws-amplify/ui`](../ui) for theming, state management, and translation logic. If you're looking for for change in these, please refer to `@aws-amplify/ui` [README](../ui/README.md). + +## Testing for Production + +After you tested your change, you can run `yarn vue build` from monorepo to run build for production.