Skip to content

Commit ee7acf7

Browse files
arundnaArundeep Nagaraj
arundna
and
Arundeep Nagaraj
authored
Changes to README and CONTRIBUTING guides for Amplify Backend (#724)
* Logo for AWS Amplify * Preview image changes * Changes to README and CONTRIBUTING files * Changed the URL to prod docs URL * Update Gen 2 nomenclature * Fix Linting Errors * Remove manual installation * fix GitHub nomenclature --------- Co-authored-by: Arundeep Nagaraj <[email protected]>
1 parent 43d09b6 commit ee7acf7

File tree

2 files changed

+91
-69
lines changed

2 files changed

+91
-69
lines changed

‎CONTRIBUTING.md‎

Lines changed: 69 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -42,17 +42,79 @@ GitHub provides additional document on [forking a repository](https://help.githu
4242

4343
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
4444

45-
## Code of Conduct
45+
## Contribute to create-amplify package
46+
47+
### Set up your local development environment
48+
49+
```sh
50+
# clone project repo
51+
cd <project directory>
52+
npm run install:local
53+
npm run test
54+
```
4655

47-
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
48-
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
49-
[email protected] with any additional questions or comments.
56+
`npm run install:local` will run `npm install`, then build all packages in the project and run `npm link`
5057

51-
## Security issue notifications
58+
`npm run test` will run all the unit tests in the project
5259

53-
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
60+
You should now be able to run the new `amplify` CLI.
5461

55-
## Contribute to create-amplify package
62+
#### Other helpful scripts
63+
64+
`npm run watch` will start the tsc server and watch for changes in all packages
65+
66+
`npm run test:coverage:threshold` will let you know if your changes are passing test coverage limits
67+
68+
`npm run test:dir packages/<package directory>` will run only the tests in that directory
69+
70+
`npm run vend` will start a local npm proxy and publish the local packages to this proxy so they can be installed / used as if they were published on npm
71+
72+
`npm run e2e` will run the E2E test suite. Note: you must have valid AWS credentials configured locally to run this command successfully.
73+
74+
### Creating changesets
75+
76+
This repo uses [changesets](https://github.com/changesets/changesets) for versioning and releasing changes.
77+
78+
All changes that affect release artifacts must have a corresponding changeset. To create a changeset run `changeset`.
79+
This will start a walkthrough to author the changeset file. This file should be committed to the repo.
80+
81+
### Publishing packages locally
82+
83+
Publishing packages locally allows you to install local package changes as if they were published to NPM. This is useful for testing or demo scenarios.
84+
85+
To set up a local npm proxy and publish the current local state to the proxy, run `npm run vend`.
86+
This will start a local npm proxy using [Verdaccio](https://verdaccio.org/) and run `changeset version` and `changeset publish`.
87+
88+
This will also point your local npm config to the local npm proxy. At this point you can npm install any packages in the repo and it will pull from the local proxy instead of directly from npm.
89+
90+
To stop the local server and reset your npm registry run `npm run stop:npm-proxy`.
91+
92+
To clear the proxy package cache run `npm run clean:npm-proxy`. This will stop the local proxy and remove all packages you have published.
93+
94+
To start the npm proxy without immediately publishing, run `npm run start:npm-proxy`.
95+
96+
To publish a snapshot to an already running npm proxy run `npm run publish:snapshot:local latest`
97+
98+
### Adding a package
99+
100+
This repo uses a monorepo structure managed by npm workspaces. All the packages in the workspace are under `packages/*`
101+
102+
There are package templates for some common scenarios in the `templates` directory.
103+
These templates can be copied to a new package directory using `npm run new -- --template=<template> --name=<new name>`
104+
`--template` specifies which template to use and `--name` specifies the new package name.
105+
Valid templates are the directories in the `templates` directory
106+
107+
If you are adding a new package that does not have a template, consider adding a template for that package type.
108+
You'll probably want to use an existing template as a starting point for the new package.
109+
110+
At a minimum, each package needs:
111+
112+
1. A `package.json` file
113+
2. A `tsconfig.json` file. This file should extend `tsconfig.base.json`
114+
3. An `api-extractor.json` file. This file should extend `api-extractor.base.json`
115+
4. An `update:api` script in the `package.json` file
116+
5. A `typedoc.json` file
117+
6. An `.npmignore` file
56118

57119
### Dev
58120

‎README.md‎

Lines changed: 22 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,39 @@
1-
## Security
2-
3-
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
1+
# Preview: AWS Amplify's new code-first DX (Gen 2) for building backends
42

5-
## License
3+
This next generation of Amplify’s backend building experience lets you author your frontend and backend definition completely with TypeScript, a file convention, and Git branch-based environments, is now available in Preview. To learn more, please visit [AWS Amplify (Gen 2)](https://docs.amplify.aws/gen2/).
64

7-
This project is licensed under the Apache-2.0 License.
5+
## Quickstart
86

9-
## Set up your local development environment
7+
To quickly get started with Amplify (Gen 2), please visit [AWS Amplify (Gen 2) Quickstart](https://docs.amplify.aws/gen2/start/quickstart/).
108

11-
```sh
12-
# clone project repo
13-
cd <project directory>
14-
npm run install:local
15-
npm run test
9+
```bash
10+
npm create amplify@latest
1611
```
1712

18-
`npm run install:local` will run `npm install`, then build all packages in the project and run `npm link`
19-
20-
`npm run test` will run all the unit tests in the project
21-
22-
You should now be able to run the new `amplify` CLI.
23-
24-
#### Other helpful scripts
25-
26-
`npm run watch` will start the tsc server and watch for changes in all packages
27-
28-
`npm run test:coverage:threshold` will let you know if your changes are passing test coverage limits
29-
30-
`npm run test:dir packages/<package directory>` will run only the tests in that directory
31-
32-
`npm run vend` will start a local npm proxy and publish the local packages to this proxy so they can be installed / used as if they were published on npm
33-
34-
`npm run e2e` will run the E2E test suite. Note: you must have valid AWS credentials configured locally to run this command successfully.
35-
36-
## Creating changesets
37-
38-
This repo uses [changesets](https://github.com/changesets/changesets) for versioning and releasing changes.
39-
40-
All changes that affect release artifacts must have a corresponding changeset. To create a changeset run `changeset`.
41-
This will start a walkthrough to author the changeset file. This file should be committed to the repo.
42-
43-
## Publishing packages locally
44-
45-
Publishing packages locally allows you to install local package changes as if they were published to NPM. This is useful for testing or demo scenarios.
46-
47-
To set up a local npm proxy and publish the current local state to the proxy, run `npm run vend`.
48-
This will start a local npm proxy using [Verdaccio](https://verdaccio.org/) and run `changeset version` and `changeset publish`.
13+
## Security
4914

50-
This will also point your local npm config to the local npm proxy. At this point you can npm install any packages in the repo and it will pull from the local proxy instead of directly from npm.
15+
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue.
5116

52-
To stop the local server and reset your npm registry run `npm run stop:npm-proxy`.
17+
## Code of Conduct
5318

54-
To clear the proxy package cache run `npm run clean:npm-proxy`. This will stop the local proxy and remove all packages you have published.
19+
This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
20+
For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
21+
[email protected] with any additional questions or comments.
5522

56-
To start the npm proxy without immediately publishing, run `npm run start:npm-proxy`.
23+
## Community
5724

58-
To publish a snapshot to an already running npm proxy run `npm run publish:snapshot:local latest`
25+
Join the [Discord Server](https://discord.com/invite/amplify).
5926

60-
## Adding a package
27+
## Tutorials
6128

62-
This repo uses a monorepo structure managed by npm workspaces. All the packages in the workspace are under `packages/*`
29+
- [Quickstart](https://docs.amplify.aws/gen2/start/quickstart/)
30+
- [Set up Amplify Auth](https://docs.amplify.aws/gen2/build-a-backend/auth/set-up-auth/)
31+
- [Set up Amplify Data](https://docs.amplify.aws/gen2/build-a-backend/data/set-up-data/)
6332

64-
There are package templates for some common scenarios in the `templates` directory.
65-
These templates can be copied to a new package directory using `npm run new -- --template=<template> --name=<new name>`
66-
`--template` specifies which template to use and `--name` specifies the new package name.
67-
Valid templates are the directories in the `templates` directory
33+
## Contributing Guidelines
6834

69-
If you are adding a new package that does not have a template, consider adding a template for that package type.
70-
You'll probably want to use an existing template as a starting point for the new package.
35+
Thank you for your interest in contributing to our project. Please visit [CONTRIBUTING](CONTRIBUTING.md) for additional information on contributing to this project.
7136

72-
At a minimum, each package needs:
37+
## License
7338

74-
1. A `package.json` file
75-
2. A `tsconfig.json` file. This file should extend `tsconfig.base.json`
76-
3. An `api-extractor.json` file. This file should extend `api-extractor.base.json`
77-
4. An `update:api` script in the `package.json` file
78-
5. A `typedoc.json` file
79-
6. An `.npmignore` file
39+
This project is licensed under the Apache-2.0 License.

0 commit comments

Comments
 (0)