From bf407ac5decfe9c0713549f8eb8bb3869bb14368 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Sun, 19 Apr 2020 20:54:30 -0600 Subject: [PATCH 01/20] Updating documentation --- .github/PULL_REQUEST_TEMPLATE.md | 1 + CODE_OF_CONDUCT.md | 76 ++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 57 ++++++++++++++++++++++++ README.md | 32 +++++++++----- 4 files changed, 156 insertions(+), 10 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 761814dd0..6d28a7553 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -63,6 +63,7 @@ ### Other: +- [ ] I have read through and followed the Contributing Guidelines - [ ] I have searched through the GitHub pull requests to ensure this PR has not already been submitted - [ ] I have updated the Dynamoose documentation (if required) given the changes I made - [ ] I have added/updated the Dynamoose test cases (if required) given the changes I made diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..53d28e87a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team [here](https://charlie.fish/contact). All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..234862fd3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,57 @@ +# Contributing to Dynamoose + +:+1::tada: **THANK YOU** for taking the time to contribute! :tada::+1: + +The following is a set of guidelines for contributing to Dynamoose and all projects in the [dynamoosejs Organization](https://github.com/dynamoosejs) on GitHub. Although these are strongly encouraged guidelines, nothing about this project is set in stone, if you believe something here should be edited, open a PR to start a discussion about it. + +## Code of Conduct + +This project and everyone participating in it is governed by the [Dynamoose Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the email address in the [Code of Conduct](CODE_OF_CONDUCT.md). + +## What should I know before I get started? + +### Documentation + +All of the documentation for the project is housed within the `docs/docs` folder. The general website is housed within the `docs` folder. It is important while contributing to Dynamoose to ensure that the documentation is complete, up to date, and helpful. + +### Resources + +It is highly encouraged to read through the following resources before contributing. + +- [README](README.md) +- [Website](https://dynamoosejs.com) + +## How Can I Contribute? + +### Reporting Bugs + +When reporting bugs please fill out the issue template with as much detail as possible. If you do not fill out the issue template with enough detail for us to debug your issue, your issue is at risk for being closed. + +### Submitting a PR + +It is highly recommended (although not required) to follow the pattern below before submitting a PR. Not every step below will be relevant to all PRs. + +#### Before + +1. **Identify a need in the project** - This can be a bug, feature request, or other change. +2. **Create a detailed issue to gauge interest** - Although most PRs are merged, we don't want you to waste time creating a PR that doesn't have the support of the community. *Please not this step is highly encouraged for larger contributions, but not required. For smaller contributions (typos, adding tests, updating documentaion, minor code changes, etc.) it is not necessary to create a seperate issue.* + +#### During + +1. **Create a fork & branch** - Before contributing to Dynamoose you must create a fork of the [main repository](https://github.com/dynamoosejs/dynamoose) and create a branch on your fork. It is highly discouraged from using a primary branch (ex. `master` or `alpha`) to make your changes. This is due to the fact that if you enable `Allow edits from maintainers` option, maintainers might commit directly to your primary branch which could cause problems if others are using your fork in their applications. +2. **Install dependencies** - Run `npm install` to install all the dependencies of the project. +3. **Maintain consistency throughout** - While working in the project, we highly encourage you to maintain the same coding style that the rest of the project uses. This means looking around at similar code and trying to adopt the same style and conventions in your code. +4. **Run tests & linter often** - It is highly encouraged to run `npm test` & `npm run lint` often to ensure you are conforming to the project guidelines. In order for a PR to be merged all tests must pass, the linter must throw no errors, and code coverage must not decrease. +5. **Write tests** - While (or better yet, before) making changes you should write tests in the test suite to ensure things work as expected. While writing tests try to consider edge cases that might occur and write test for those edge cases (ex. what happens if you a user passes in no arguments, or what happens if the type passed in is not the type you expect). +6. **Update documentation** - It is encouraged throughout +7. **Commit small & often** - Please commit changes often and keep commit size to a minimum. It is highly discouraged from creating one massive commit with all of your changes in it. Every commit should also aim to pass the linter and tests. Commit messages should also be detailed enough to give a good explaination of the change made. Commit messages such as `changes` or `did stuff` are considered **poor** commit messages. + +#### After + +1. **Submit the PR** - When submitting the PR it is important to fill out the complete PR template. This ensures reviewers of your PR can easily understand what is going on and make sure all guidelines and requirements have been met. It is also highly recommended to enable the `Allow edits from maintainers` option (be aware that enabling this option means that maintainers have the right to commit to your branch at any time, *we do use this ability*). +2. **Be prepared for questions and suggestions** - As others review your PR it is important to be available to answer questions and promptly respond to code suggestions. Stale PRs run the risk of being closed, even if it's a large change or a lot of effort was put into it. +3. **Ask others for reviews** - If you know someone who is anticipating your work, ask them to test your branch and leave a detailed review on the PR. + +#### Release + +Dynamoose does not currently have a release schedule that we conform to. We atttempt to batch work into a release every so often. If you have a need that requires us releasing a version sooner, please notify us, and we will attempt to cut a new release earlier (however this is not guaranteed, and you are still welcome to point to a branch in NPM if we are unable to release on your timeline). diff --git a/README.md b/README.md index 6f1aba0af..f4a1d34ef 100755 --- a/README.md +++ b/README.md @@ -34,20 +34,32 @@ --- -# Dynamoose Version 2.0 is still In Development. Please [contact me](https://charlie.fish/contact) with any feedback or questions. +Dynamoose is a modeling tool for Amazon's DynamoDB (inspired by [Mongoose](https://mongoosejs.com/)). -Dynamoose is a modeling tool for Amazon's DynamoDB (inspired by [Mongoose](https://mongoosejs.com/)) +### Getting Started +Take a look at our [website](https://dynamoosejs.com) for information about how to get started. -## Getting Started +### Resources -### Installation +#### General -```sh -$ npm i dynamoose@beta -``` +- [Website](https://dynamoosejs.com) +- [Contributing Guide](CONTRIBUTING.md) +- [Changelog](CHANGELOG.md) +- [License](LICENSE) -## Documentation +#### Social -- [v2](https://github.com/dynamoosejs/dynamoose/tree/master/docs) -- [v1](https://dynamoosejs.com) +- [Slack](https://join.slack.com/t/dynamoose/shared_invite/enQtODM4OTI0MTc1NDc3LWI3MmNhMThmNmJmZDk5MmUxOTZmMGEwNGQzNTRkMjhjZGJlNGM5M2JmZjMzMzlkODRhMGY3MTQ5YjQ2Nzg3YTY) +- [Twitter](https://twitter.com/DynamooseJS) + +### Branch Strategy + +Below you will find the current branch strategy for the project. Work taking place on the branches listed below might be further ahead than the versions on NPM. All documentation links found below will also be reflective of the published version on NPM. If you would like to live dangouragely and run non released versions, you can run `npm install dynamoosejs/dynamoose#BRANCH` (replacing `BRANCH` with the branch listed below). You will also find the most up to date documentation in the `docs` folder of the branch. + +| Branch | Version | NPM Tag | Links | +| --- | --- | --- | --- | +| [`v1.11.1`](https://github.com/dynamoosejs/dynamoose/tree/v1.11.1) (tag) | 1.11.1 | latest | - [Documentation](https://dynamoosejs.com) | +| [`master`](https://github.com/dynamoosejs/dynamoose/tree/master) | 2.0.0 | beta | - [Documentation](https://github.com/dynamoosejs/dynamoose/tree/master/docs/docs)
- [Issue](https://github.com/dynamoosejs/dynamoose/issues/709) | +| [`alpha`](https://github.com/dynamoosejs/dynamoose/tree/alpha) | 2.1.0 | alpha | - [Documentation](https://github.com/dynamoosejs/dynamoose/tree/alpha/docs/docs)
- [Issue](https://github.com/dynamoosejs/dynamoose/issues/788) | From cf1c0ac4cd1772e60550848c736d8ad34cf1a024 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Sun, 19 Apr 2020 23:27:27 -0600 Subject: [PATCH 02/20] Adding more information to contributing guidelines --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 234862fd3..9de4a0d03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ The following is a set of guidelines for contributing to Dynamoose and all proje ## Code of Conduct -This project and everyone participating in it is governed by the [Dynamoose Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the email address in the [Code of Conduct](CODE_OF_CONDUCT.md). +This project and everyone participating in it is governed by the [Dynamoose Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the contact method in the [Code of Conduct](CODE_OF_CONDUCT.md). ## What should I know before I get started? @@ -35,6 +35,7 @@ It is highly recommended (although not required) to follow the pattern below bef 1. **Identify a need in the project** - This can be a bug, feature request, or other change. 2. **Create a detailed issue to gauge interest** - Although most PRs are merged, we don't want you to waste time creating a PR that doesn't have the support of the community. *Please not this step is highly encouraged for larger contributions, but not required. For smaller contributions (typos, adding tests, updating documentaion, minor code changes, etc.) it is not necessary to create a seperate issue.* +3. **Read through the `package.json`** - The `package.json` file in the root of the repository has a **lot** of useful information about the project. Especially read through the scripts section, as a lot of those scripts can help speed up your development process when working in Dynamoose. #### During From 172f6e26f15d2223c5e9cd802848d2003152b0f2 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Mon, 20 Apr 2020 00:53:52 -0600 Subject: [PATCH 03/20] Improving documentation with getting started section --- docs/docs/api/{General.md => Dynamoose.md} | 8 --- docs/docs/api/Transaction.md | 2 +- docs/docs/getting_started/Configure.mdx | 67 ++++++++++++++++++++++ docs/docs/getting_started/Import.mdx | 27 +++++++++ docs/docs/getting_started/Install.mdx | 23 ++++++++ docs/docs/getting_started/Introduction.mdx | 15 +++++ docs/docusaurus.config.js | 3 + docs/package-lock.json | 5 ++ docs/package.json | 1 + docs/sidebars.js | 10 +++- docs/src/pages/index.js | 2 +- docs/src/plugins/remark-npm2yarn.js | 65 +++++++++++++++++++++ 12 files changed, 216 insertions(+), 12 deletions(-) rename docs/docs/api/{General.md => Dynamoose.md} (97%) create mode 100644 docs/docs/getting_started/Configure.mdx create mode 100644 docs/docs/getting_started/Import.mdx create mode 100644 docs/docs/getting_started/Install.mdx create mode 100644 docs/docs/getting_started/Introduction.mdx create mode 100644 docs/src/plugins/remark-npm2yarn.js diff --git a/docs/docs/api/General.md b/docs/docs/api/Dynamoose.md similarity index 97% rename from docs/docs/api/General.md rename to docs/docs/api/Dynamoose.md index abe0bdbaa..60148d222 100644 --- a/docs/docs/api/General.md +++ b/docs/docs/api/Dynamoose.md @@ -1,11 +1,3 @@ -You can access Dynamoose by requiring the library. For example: - -```js -const dynamoose = require("dynamoose"); -``` - -The Dynamoose object is the entry point to everything you will do with this package. - ## dynamoose.aws The `dynamoose.aws` object is used to set AWS level settings for Dynamoose. This includes things like setting a custom DDB instance, setting the AWS region, access keys, and more. diff --git a/docs/docs/api/Transaction.md b/docs/docs/api/Transaction.md index de72243ef..4150ebba9 100644 --- a/docs/docs/api/Transaction.md +++ b/docs/docs/api/Transaction.md @@ -1,4 +1,4 @@ -DynamoDB supports running transactions in your database. These transactions are all or nothing, meaning the entire transaction will succeed, or the entire transaction will fail. In the event the transaction fails, the state of the database will be the exact same as if the transaction didn't take place at all. +DynamoDB supports running transactions in your database(s). These transactions are all or nothing, meaning the entire transaction will succeed, or the entire transaction will fail. In the event the transaction fails, the state of the database will be the exact same as if the transaction didn't take place at all (ex. no documents will have been modified). ## dynamoose.transaction(transactions[, settings][, callback]) diff --git a/docs/docs/getting_started/Configure.mdx b/docs/docs/getting_started/Configure.mdx new file mode 100644 index 000000000..ad2675baf --- /dev/null +++ b/docs/docs/getting_started/Configure.mdx @@ -0,0 +1,67 @@ +Dynamoose interacts directly with the [AWS-SDK](https://www.npmjs.com/package/aws-sdk), therefore, it is required that you authenticate and provide valid credentials so Dynamoose can successfully make requests to DynamoDB. + +It is recommended that you do this as early in the application life cycle as possible to prevent issues where Dynamoose will try to make requests to DynamoDB that are unauthenticated. + +There are a few ways to do this. + +## Environment Variables + +You can use environment variables to setup your configuration. + +```bash +export AWS_ACCESS_KEY_ID = "Your AWS Access Key ID" +export AWS_SECRET_ACCESS_KEY = "Your AWS Secret Access Key" +export AWS_REGION = "us-east-1" +``` + +## Programatically + +### Global + +The following code will change the AWS-SDK global settings to use the configuration options. + +```js +dynamoose.aws.sdk.config.update({ + "accessKeyId": "AKID", + "secretAccessKey": "SECRET", + "region": "us-east-1" +}); +``` + +### Dynamoose Specific + +The following code will create a new DynamoDB instance with the specific configuration options and use that in Dynamoose. + +```js +// Create new DynamoDB instance +const ddb = new dynamoose.aws.sdk.DynamoDB({ + "accessKeyId": "AKID", + "secretAccessKey": "SECRET", + "region": "us-east-1" +}); + +// Set DynamoDB instance to the Dynamoose DDB instance +dynamoose.aws.ddb.set(ddb); +``` + +## IAM Role + +If you are running Dynamoose in an environment that has an IAM role attached to it (ex. [Lambda](https://aws.amazon.com/lambda/) or [EC2](https://aws.amazon.com/ec2/)), you do not need to do any additional configuration so long as your IAM role has appropriate permissions to access DynamoDB. + +## Local + +You can also configure Dynamoose to use [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html). + +If your DynamoDB Local server is running on `http://localhost:8000` you can use the following command. + +```js +dynamoose.aws.ddb.local(); +``` + +Otherwise if your local DynamoDB server is running at a different location you can pass that in as an argument. For example if your server is running at `http://localhost:1234` you can run the following command. + +```js +dynamoose.aws.ddb.local("http://localhost:1234"); +``` + +Read more about this method [here](/api/Dynamoose#dynamooseawsddblocalendpoint). diff --git a/docs/docs/getting_started/Import.mdx b/docs/docs/getting_started/Import.mdx new file mode 100644 index 000000000..75b1223cf --- /dev/null +++ b/docs/docs/getting_started/Import.mdx @@ -0,0 +1,27 @@ +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +In order to use Dynamoose you must import it or require it in your project. This will make the `dynamoose` namespace accessible so you can use things like models, schemas, and more. + + + + +```js +const dynamoose = require("dynamoose"); +``` + + + + +```js +import { dynamoose } from "dynamoose"; +``` + + + diff --git a/docs/docs/getting_started/Install.mdx b/docs/docs/getting_started/Install.mdx new file mode 100644 index 000000000..7d6d69593 --- /dev/null +++ b/docs/docs/getting_started/Install.mdx @@ -0,0 +1,23 @@ +## Standard + +To install Dynamoose you can run the following command. + +```bash npm2yarn +npm install --save dynamoose +``` + +## Prerelease + +At times we will also have prerelease versions of Dynamoose that you can install. An example of this would be the following command. + +```bash npm2yarn +npm install --save dynamoose@beta +``` + +## Branch + +You can also install Dynamoose from a specific branch. + +```bash npm2yarn +npm install --save dynamoosejs/dynamoose#master +``` diff --git a/docs/docs/getting_started/Introduction.mdx b/docs/docs/getting_started/Introduction.mdx new file mode 100644 index 000000000..9759fb9f1 --- /dev/null +++ b/docs/docs/getting_started/Introduction.mdx @@ -0,0 +1,15 @@ +## Description + +Dynamoose is a modeling tool for Amazon's DynamoDB. Dynamoose is heavily inspired by [Mongoose](https://mongoosejs.com/), which means if you are coming from Mongoose the syntax will be very familar. + +## Key Features + +- Type safety +- High level API +- Easy to use syntax +- Ability to transform data before saving or retrieving documents +- Strict data modeling (validation, required attributes, and more) +- Support for DynamoDB Transactions +- Powerful Conditional/Filtering Support +- Callback & Promise support +- And **MANY** more diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 1f7bceca5..f28e1ac3f 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -59,6 +59,9 @@ module.exports = { "routeBasePath": "", "sidebarPath": require.resolve("./sidebars.js"), "editUrl": "https://github.com/dynamoosejs/dynamoose/edit/master/docs", + "remarkPlugins": [ + require("./src/plugins/remark-npm2yarn") + ], }, "theme": { "customCss": require.resolve("./src/css/custom.css"), diff --git a/docs/package-lock.json b/docs/package-lock.json index 7594c0402..13ee3951c 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -7035,6 +7035,11 @@ } } }, + "npm-to-yarn": { + "version": "1.0.0-2", + "resolved": "https://registry.npmjs.org/npm-to-yarn/-/npm-to-yarn-1.0.0-2.tgz", + "integrity": "sha512-uyf4baF5ejzu/GzLQTyJpwnKyCzbsN8tbgKUyLU67RAJkIas+qDvZuthS48b6c81NDh6wAVRCLz3FdApgL1MmQ==" + }, "nprogress": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/nprogress/-/nprogress-0.2.0.tgz", diff --git a/docs/package.json b/docs/package.json index 15dbb18b8..07516bbfe 100644 --- a/docs/package.json +++ b/docs/package.json @@ -11,6 +11,7 @@ "@docusaurus/core": "^2.0.0-alpha.50", "@docusaurus/preset-classic": "^2.0.0-alpha.50", "classnames": "^2.2.6", + "npm-to-yarn": "^1.0.0-2", "react": "^16.8.4", "react-dom": "^16.8.4" }, diff --git a/docs/sidebars.js b/docs/sidebars.js index e460e04d4..aa428f803 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,14 +1,20 @@ module.exports = { "sidebar": { + "Getting Started": [ + "getting_started/Introduction", + "getting_started/Install", + "getting_started/Import", + "getting_started/Configure" + ], "API": [ - "api/General", "api/Schema", "api/Model", "api/Document", "api/Condition", "api/Query", "api/Scan", - "api/Transaction" + "api/Transaction", + "api/Dynamoose" ], "Other": [ "FAQ" diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js index 425114b15..525a90c30 100644 --- a/docs/src/pages/index.js +++ b/docs/src/pages/index.js @@ -4,7 +4,7 @@ import {Redirect} from "@docusaurus/router"; import useBaseUrl from "@docusaurus/useBaseUrl"; function Home() { - return ; + return ; } export default Home; diff --git a/docs/src/plugins/remark-npm2yarn.js b/docs/src/plugins/remark-npm2yarn.js new file mode 100644 index 000000000..f33c0cdd3 --- /dev/null +++ b/docs/src/plugins/remark-npm2yarn.js @@ -0,0 +1,65 @@ +const npmToYarn = require("npm-to-yarn"); + +const convertNpmToYarn = (npmCode) => npmToYarn(npmCode, "yarn"); + +const transformNode = (node) => { + const npmCode = node.value; + const yarnCode = convertNpmToYarn(node.value); + return [ + { + "type": "jsx", + "value": ``, + }, + { + "type": node.type, + "lang": node.lang, + "value": npmCode, + }, + { + "type": "jsx", + "value": `\n`, + }, + { + "type": node.type, + "lang": node.lang, + "value": yarnCode, + }, + { + "type": "jsx", + "value": "\n", + }, + ]; +}; + +const matchNode = (node) => node.type === "code" && node.meta === "npm2yarn"; +const nodeForImport = { + "type": "import", + "value": `import Tabs from "@theme/Tabs";\nimport TabItem from "@theme/TabItem";`, +}; + +module.exports = () => { + let transformed = false; + const transformer = (node) => { + if (matchNode(node)) { + transformed = true; + return transformNode(node); + } + if (Array.isArray(node.children)) { + let index = 0; + while (index < node.children.length) { + const result = transformer(node.children[index]); + if (result) { + node.children.splice(index, 1, ...result); + index += result.length; + } else { + index += 1; + } + } + } + if (node.type === "root" && transformed) { + node.children.unshift(nodeForImport); + } + return null; + }; + return transformer; +}; From 805b41ef041e3c5075b9559fcfd36f2d0b81adb7 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Mon, 20 Apr 2020 17:42:50 -0600 Subject: [PATCH 04/20] Adding action for publishing site closes #828 --- .github/workflows/publish.yml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index fc5335545..c9e704dd0 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -46,3 +46,22 @@ jobs: # env: # TAG: ${{ needs.getinfo.outputs.npmtag }} # NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + publishsite: + needs: getinfo + runs-on: ubuntu-latest + if: needs.getinfo.outputs.npmtag == 'latest' + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v1 + - run: npm run site:install + - run: npm run site:build + - uses: jakejarvis/s3-sync-action@v0.5.1 + with: + args: --follow-symlinks --delete + env: + AWS_S3_BUCKET: ${{ secrets.AWS_SITE_S3_BUCKET }} + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + AWS_REGION: 'us-west-2' + SOURCE_DIR: 'docs/build' From 8bf6ec4abad194fad41f2c30ee2326bc4180095f Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Mon, 20 Apr 2020 19:20:04 -0600 Subject: [PATCH 05/20] Adding support for caching website --- .github/workflows/publish.yml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index c9e704dd0..e8c16d325 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -58,10 +58,19 @@ jobs: - run: npm run site:build - uses: jakejarvis/s3-sync-action@v0.5.1 with: - args: --follow-symlinks --delete + args: --follow-symlinks --delete --cache-control 's-maxage=604800, max-age=0' env: AWS_S3_BUCKET: ${{ secrets.AWS_SITE_S3_BUCKET }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_REGION: 'us-west-2' SOURCE_DIR: 'docs/build' + - name: Purge Cloudflare Cache + run: | + curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE/purge_cache" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + --data '{"purge_everything":true}' + env: + TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }} + ZONE: ${{ secrets.CLOUDFLARE_ZONE }} From 335ec2d6d175a5a53b26104752d002804cc8159e Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 20:04:24 -0600 Subject: [PATCH 06/20] Adding documentation about MCVE to contributing guide --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9de4a0d03..12152cc4f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,16 @@ It is highly encouraged to read through the following resources before contribut When reporting bugs please fill out the issue template with as much detail as possible. If you do not fill out the issue template with enough detail for us to debug your issue, your issue is at risk for being closed. +#### Minimal, Complete and Verifiable Example (MCVE) + +One of the most important things when submitting an issue is to provide a *Minimal, Complete and Verifiable Example* (or MCVE for short). If you are reporting a bug it is important for us to be able to test and debug your code as quickly as possible. + +- *Minimal* – Use as little code as possible that still produces the same problem +- *Complete* – Provide all parts needed to reproduce your problem +- *Reproducible* – Test the code to make sure it reproduces the problem + +Without following these steps when creating code examples it is nearly impossible for us to debug your issue. Help us help you by putting time and care into code examples. Not following this guideline puts your issue at risk for being closed. + ### Submitting a PR It is highly recommended (although not required) to follow the pattern below before submitting a PR. Not every step below will be relevant to all PRs. From 0951f2f82baa4da764990d103da075d6d8356fe4 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 20:04:33 -0600 Subject: [PATCH 07/20] Updating website footer with more relevant links --- docs/docusaurus.config.js | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index f28e1ac3f..7be92f03b 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -28,7 +28,7 @@ module.exports = { "style": "dark", "links": [ { - "title": "Resources", + "title": "Social", "items": [ { "label": "GitHub", @@ -48,6 +48,27 @@ module.exports = { } ], }, + { + "title": "Other Resources", + "items": [ + { + "label": "Contributing Guidelines", + "href": "https://github.com/dynamoosejs/dynamoose/blob/master/CONTRIBUTING.md", + }, + { + "label": "Code of Conduct", + "href": "https://github.com/dynamoosejs/dynamoose/blob/master/CODE_OF_CONDUCT.md", + }, + { + "label": "Changelog", + "href": "https://github.com/dynamoosejs/dynamoose/blob/master/CHANGELOG.md", + }, + { + "label": "License", + "href": "https://github.com/dynamoosejs/dynamoose/blob/master/LICENSE.md", + } + ], + }, ], }, }, From 40e252c46445304c69831cec3951afae70c17b15 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 20:07:29 -0600 Subject: [PATCH 08/20] Adding code of conduct link to README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f4a1d34ef..21b912ad6 100755 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ Take a look at our [website](https://dynamoosejs.com) for information about how - [Website](https://dynamoosejs.com) - [Contributing Guide](CONTRIBUTING.md) +- [Code of Conduct](CODE_OF_CONDUCT.md) - [Changelog](CHANGELOG.md) - [License](LICENSE) From d409dc743b105c8b8c3a5234f097a6660ebcd048 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 20:09:32 -0600 Subject: [PATCH 09/20] Updating README to point to v1.dynamoosejs.com for v1 docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 21b912ad6..610a06645 100755 --- a/README.md +++ b/README.md @@ -61,6 +61,6 @@ Below you will find the current branch strategy for the project. Work taking pla | Branch | Version | NPM Tag | Links | | --- | --- | --- | --- | -| [`v1.11.1`](https://github.com/dynamoosejs/dynamoose/tree/v1.11.1) (tag) | 1.11.1 | latest | - [Documentation](https://dynamoosejs.com) | +| [`v1.11.1`](https://github.com/dynamoosejs/dynamoose/tree/v1.11.1) (tag) | 1.11.1 | latest | - [Documentation](https://v1.dynamoosejs.com) | | [`master`](https://github.com/dynamoosejs/dynamoose/tree/master) | 2.0.0 | beta | - [Documentation](https://github.com/dynamoosejs/dynamoose/tree/master/docs/docs)
- [Issue](https://github.com/dynamoosejs/dynamoose/issues/709) | | [`alpha`](https://github.com/dynamoosejs/dynamoose/tree/alpha) | 2.1.0 | alpha | - [Documentation](https://github.com/dynamoosejs/dynamoose/tree/alpha/docs/docs)
- [Issue](https://github.com/dynamoosejs/dynamoose/issues/788) | From 537c6180763b920b45500b431eac1525c87c33e7 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 21:23:08 -0600 Subject: [PATCH 10/20] Making Transaction documentation more clear --- docs/docs/api/Transaction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/api/Transaction.md b/docs/docs/api/Transaction.md index 4150ebba9..ea0abe214 100644 --- a/docs/docs/api/Transaction.md +++ b/docs/docs/api/Transaction.md @@ -1,4 +1,4 @@ -DynamoDB supports running transactions in your database(s). These transactions are all or nothing, meaning the entire transaction will succeed, or the entire transaction will fail. In the event the transaction fails, the state of the database will be the exact same as if the transaction didn't take place at all (ex. no documents will have been modified). +DynamoDB supports running DynamoDB Transactions in your database. Transactions are all or nothing, meaning the entire transaction will succeed, or the entire transaction will fail. In the event the transaction fails, the state of the database will be the exact same as if the transaction didn't take place at all (ex. no documents will have been modified). You are also able to run these Transactions across multiple tables. ## dynamoose.transaction(transactions[, settings][, callback]) From da826f20340c0c0f1d02b28e5a7828a85729174c Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 21:24:40 -0600 Subject: [PATCH 11/20] Reorganizing location for website guides --- docs/docs/{api => guide}/Condition.md | 0 docs/docs/{api => guide}/Document.md | 0 docs/docs/{api => guide}/Dynamoose.md | 0 docs/docs/{api => guide}/Model.md | 0 docs/docs/{api => guide}/Query.md | 0 docs/docs/{api => guide}/Scan.md | 0 docs/docs/{api => guide}/Schema.md | 0 docs/docs/{api => guide}/Transaction.md | 0 docs/docs/{ => other}/FAQ.md | 0 docs/sidebars.js | 20 ++++++++++---------- 10 files changed, 10 insertions(+), 10 deletions(-) rename docs/docs/{api => guide}/Condition.md (100%) rename docs/docs/{api => guide}/Document.md (100%) rename docs/docs/{api => guide}/Dynamoose.md (100%) rename docs/docs/{api => guide}/Model.md (100%) rename docs/docs/{api => guide}/Query.md (100%) rename docs/docs/{api => guide}/Scan.md (100%) rename docs/docs/{api => guide}/Schema.md (100%) rename docs/docs/{api => guide}/Transaction.md (100%) rename docs/docs/{ => other}/FAQ.md (100%) diff --git a/docs/docs/api/Condition.md b/docs/docs/guide/Condition.md similarity index 100% rename from docs/docs/api/Condition.md rename to docs/docs/guide/Condition.md diff --git a/docs/docs/api/Document.md b/docs/docs/guide/Document.md similarity index 100% rename from docs/docs/api/Document.md rename to docs/docs/guide/Document.md diff --git a/docs/docs/api/Dynamoose.md b/docs/docs/guide/Dynamoose.md similarity index 100% rename from docs/docs/api/Dynamoose.md rename to docs/docs/guide/Dynamoose.md diff --git a/docs/docs/api/Model.md b/docs/docs/guide/Model.md similarity index 100% rename from docs/docs/api/Model.md rename to docs/docs/guide/Model.md diff --git a/docs/docs/api/Query.md b/docs/docs/guide/Query.md similarity index 100% rename from docs/docs/api/Query.md rename to docs/docs/guide/Query.md diff --git a/docs/docs/api/Scan.md b/docs/docs/guide/Scan.md similarity index 100% rename from docs/docs/api/Scan.md rename to docs/docs/guide/Scan.md diff --git a/docs/docs/api/Schema.md b/docs/docs/guide/Schema.md similarity index 100% rename from docs/docs/api/Schema.md rename to docs/docs/guide/Schema.md diff --git a/docs/docs/api/Transaction.md b/docs/docs/guide/Transaction.md similarity index 100% rename from docs/docs/api/Transaction.md rename to docs/docs/guide/Transaction.md diff --git a/docs/docs/FAQ.md b/docs/docs/other/FAQ.md similarity index 100% rename from docs/docs/FAQ.md rename to docs/docs/other/FAQ.md diff --git a/docs/sidebars.js b/docs/sidebars.js index aa428f803..47a7538c4 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -6,18 +6,18 @@ module.exports = { "getting_started/Import", "getting_started/Configure" ], - "API": [ - "api/Schema", - "api/Model", - "api/Document", - "api/Condition", - "api/Query", - "api/Scan", - "api/Transaction", - "api/Dynamoose" + "Guide": [ + "guide/Schema", + "guide/Model", + "guide/Document", + "guide/Condition", + "guide/Query", + "guide/Scan", + "guide/Transaction", + "guide/Dynamoose" ], "Other": [ - "FAQ" + "other/FAQ" ] }, }; From 37e4030d5f14364d1ab384815639a927394f39b9 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 21:44:03 -0600 Subject: [PATCH 12/20] Moving changelog template to separate file --- publish/CHANGELOG_TEMPLATE.md | 15 +++++++++++++++ publish/index.js | 5 +++-- 2 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 publish/CHANGELOG_TEMPLATE.md diff --git a/publish/CHANGELOG_TEMPLATE.md b/publish/CHANGELOG_TEMPLATE.md new file mode 100644 index 000000000..f5fafef78 --- /dev/null +++ b/publish/CHANGELOG_TEMPLATE.md @@ -0,0 +1,15 @@ +This release ________ + +Please comment or [contact me](https://charlie.fish/contact) if you have any questions about this release. + +### 🚨 Breaking Changes 🚨 + +### Major New Features + +### General + +### Bug Fixes + +### Documentation + +### Other diff --git a/publish/index.js b/publish/index.js index c48eff642..0d68b66a6 100644 --- a/publish/index.js +++ b/publish/index.js @@ -102,12 +102,13 @@ let package = require("../package.json"); const versionInfo = retrieveInformation(results.version); const versionFriendlyTitle = `Version ${[versionInfo.main, utils.capitalize_first_letter(versionInfo.tag || ""), versionInfo.tagNumber].filter((a) => Boolean(a)).join(" ")}`; const changelogFilePath = path.join(os.tmpdir(), `${results.version}-changelog.md`); - await fs.writeFile(changelogFilePath, `## ${versionFriendlyTitle}\n\nThis release ________\n\nPlease comment or [contact me](https://charlie.fish/contact) if you have any questions about this release.\n\n### Major New Features\n\n### General\n\n### Bug Fixes\n\n### Documentation\n\n### Other`); + const changelogTemplate = `## ${versionFriendlyTitle}\n\n${await fs.readFile(path.join(__dirname, "CHANGELOG_TEMPLATE.md"), "utf8")}`; + await fs.writeFile(changelogFilePath, changelogTemplate); await exec(`code ${changelogFilePath}`); const pendingChangelogSpinner = ora("Waiting for user to finish changelog, press enter to continue.").start(); await keypress(); pendingChangelogSpinner.succeed("Finished changelog"); - const versionChangelog = await fs.readFile(changelogFilePath, "utf8"); + const versionChangelog = (await fs.readFile(changelogFilePath, "utf8")).trim(); if (!versionInfo.isPrerelease) { const existingChangelog = await fs.readFile(path.join(__dirname, "..", "CHANGELOG.md"), "utf8"); const existingChangelogArray = existingChangelog.split("\n---\n"); From 3f63ee4f9514446677a7c032b7b5f4600c0f41aa Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 21:50:56 -0600 Subject: [PATCH 13/20] Updating contributing guidelines --- CONTRIBUTING.md | 18 +++++++++--------- internal/ContributingGuidelines.md | 5 ----- 2 files changed, 9 insertions(+), 14 deletions(-) delete mode 100644 internal/ContributingGuidelines.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12152cc4f..f40d9eee4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ :+1::tada: **THANK YOU** for taking the time to contribute! :tada::+1: -The following is a set of guidelines for contributing to Dynamoose and all projects in the [dynamoosejs Organization](https://github.com/dynamoosejs) on GitHub. Although these are strongly encouraged guidelines, nothing about this project is set in stone, if you believe something here should be edited, open a PR to start a discussion about it. +The following is a set of guidelines for contributing to Dynamoose and all projects in the [dynamoosejs Organization](https://github.com/dynamoosejs) on GitHub. Although these are strongly encouraged guidelines, nothing about this project is set in stone, if you believe something here should be edited, open a pull request to start a discussion about it. ## Code of Conduct @@ -37,14 +37,14 @@ One of the most important things when submitting an issue is to provide a *Minim Without following these steps when creating code examples it is nearly impossible for us to debug your issue. Help us help you by putting time and care into code examples. Not following this guideline puts your issue at risk for being closed. -### Submitting a PR +### Submitting a Pull Request (PR) -It is highly recommended (although not required) to follow the pattern below before submitting a PR. Not every step below will be relevant to all PRs. +It is highly recommended (although not required) to follow the pattern below before submitting a pull request. Not every step below will be relevant to all pull requests. #### Before 1. **Identify a need in the project** - This can be a bug, feature request, or other change. -2. **Create a detailed issue to gauge interest** - Although most PRs are merged, we don't want you to waste time creating a PR that doesn't have the support of the community. *Please not this step is highly encouraged for larger contributions, but not required. For smaller contributions (typos, adding tests, updating documentaion, minor code changes, etc.) it is not necessary to create a seperate issue.* +2. **Create a detailed issue to gauge interest** - Although most pull requests are merged, we don't want you to waste time creating a pull request that doesn't have the support of the community. This doesn't mean that even if the community supports an issue that the corosponding pull request will be merged, but it increases the chances with community support. *This step is highly encouraged for larger contributions, but not required. For smaller contributions (typos, adding tests, updating documentaion, minor code changes, etc.) it is not necessary to create a seperate issue.* 3. **Read through the `package.json`** - The `package.json` file in the root of the repository has a **lot** of useful information about the project. Especially read through the scripts section, as a lot of those scripts can help speed up your development process when working in Dynamoose. #### During @@ -52,16 +52,16 @@ It is highly recommended (although not required) to follow the pattern below bef 1. **Create a fork & branch** - Before contributing to Dynamoose you must create a fork of the [main repository](https://github.com/dynamoosejs/dynamoose) and create a branch on your fork. It is highly discouraged from using a primary branch (ex. `master` or `alpha`) to make your changes. This is due to the fact that if you enable `Allow edits from maintainers` option, maintainers might commit directly to your primary branch which could cause problems if others are using your fork in their applications. 2. **Install dependencies** - Run `npm install` to install all the dependencies of the project. 3. **Maintain consistency throughout** - While working in the project, we highly encourage you to maintain the same coding style that the rest of the project uses. This means looking around at similar code and trying to adopt the same style and conventions in your code. -4. **Run tests & linter often** - It is highly encouraged to run `npm test` & `npm run lint` often to ensure you are conforming to the project guidelines. In order for a PR to be merged all tests must pass, the linter must throw no errors, and code coverage must not decrease. -5. **Write tests** - While (or better yet, before) making changes you should write tests in the test suite to ensure things work as expected. While writing tests try to consider edge cases that might occur and write test for those edge cases (ex. what happens if you a user passes in no arguments, or what happens if the type passed in is not the type you expect). +4. **Run tests & linter often** - It is highly encouraged to run `npm test` & `npm run lint` often to ensure you are conforming to the project guidelines. In order for a pull request to be merged all tests must pass, the linter must throw no errors, and test code coverage must not decrease. +5. **Write tests** - While (or better yet, before) making changes you should write tests in the test suite to ensure things work as expected. While writing tests try to consider edge cases that might occur and write test for those edge cases (ex. what happens if you a user passes in no arguments, or what happens if the type passed in is not the type you expect). Your pull request will not be merged if it decreases the code coverage for tests, so it is important to write tests to ensure any code added or modified is covered by tests. It is also important that your tests do not print any output to the console or logs, this includes `console.log`, UncaughtPromiseExceptions, etc. All logs printed should come directly from Mocha. 6. **Update documentation** - It is encouraged throughout 7. **Commit small & often** - Please commit changes often and keep commit size to a minimum. It is highly discouraged from creating one massive commit with all of your changes in it. Every commit should also aim to pass the linter and tests. Commit messages should also be detailed enough to give a good explaination of the change made. Commit messages such as `changes` or `did stuff` are considered **poor** commit messages. #### After -1. **Submit the PR** - When submitting the PR it is important to fill out the complete PR template. This ensures reviewers of your PR can easily understand what is going on and make sure all guidelines and requirements have been met. It is also highly recommended to enable the `Allow edits from maintainers` option (be aware that enabling this option means that maintainers have the right to commit to your branch at any time, *we do use this ability*). -2. **Be prepared for questions and suggestions** - As others review your PR it is important to be available to answer questions and promptly respond to code suggestions. Stale PRs run the risk of being closed, even if it's a large change or a lot of effort was put into it. -3. **Ask others for reviews** - If you know someone who is anticipating your work, ask them to test your branch and leave a detailed review on the PR. +1. **Submit the pull request** - When submitting the pull request it is important to fill out the complete pull request template. This ensures reviewers of your pull request can easily understand what is going on and make sure all guidelines and requirements have been met. It is also highly recommended to enable the `Allow edits from maintainers` option (be aware that enabling this option means that maintainers have the right to commit to your branch at any time, *we do use this ability*). +2. **Be prepared for questions and suggestions** - As others review your pull request it is important to be available to answer questions and promptly respond to code suggestions. Stale pull requests run the risk of being closed, even if it's a large change or a lot of effort was put into it. +3. **Ask others for reviews** - If you know someone who is anticipating your work, ask them to test your branch and leave a detailed review on the pull request. #### Release diff --git a/internal/ContributingGuidelines.md b/internal/ContributingGuidelines.md deleted file mode 100644 index 228c28192..000000000 --- a/internal/ContributingGuidelines.md +++ /dev/null @@ -1,5 +0,0 @@ -# Contributing Guidelines Draft - -- No logs should be printed when running `npm test`. This includes both `console.log` statements as well as UncaughtPromiseExceptions. All logs printed should come directly from Mocha. -- Test coverage should remain at 100%, and cover as many edge cases as possible. -- Linter should pass with no errors. From 7231477f53f85ac92f5c515400c187e451ef3b69 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 21:57:11 -0600 Subject: [PATCH 14/20] Adding more detail in contributing guide about package.json scripts --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f40d9eee4..bfce237e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ It is highly recommended (although not required) to follow the pattern below bef 1. **Identify a need in the project** - This can be a bug, feature request, or other change. 2. **Create a detailed issue to gauge interest** - Although most pull requests are merged, we don't want you to waste time creating a pull request that doesn't have the support of the community. This doesn't mean that even if the community supports an issue that the corosponding pull request will be merged, but it increases the chances with community support. *This step is highly encouraged for larger contributions, but not required. For smaller contributions (typos, adding tests, updating documentaion, minor code changes, etc.) it is not necessary to create a seperate issue.* -3. **Read through the `package.json`** - The `package.json` file in the root of the repository has a **lot** of useful information about the project. Especially read through the scripts section, as a lot of those scripts can help speed up your development process when working in Dynamoose. +3. **Read through the `package.json`** - The `package.json` file in the root of the repository has a **lot** of useful information about the project. Especially read through the `scripts` section, as a lot of those scripts can help speed up your development process when working in Dynamoose. There are scripts for running tests, building the website, debugging code, fixing lint issues, etc. #### During From 684bb2058207581558a5c214ea95b0b40eba2cb2 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 21:57:22 -0600 Subject: [PATCH 15/20] Adding section to contributing guide for deploying release --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bfce237e9..a1bf81ad2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,3 +66,13 @@ It is highly recommended (although not required) to follow the pattern below bef #### Release Dynamoose does not currently have a release schedule that we conform to. We atttempt to batch work into a release every so often. If you have a need that requires us releasing a version sooner, please notify us, and we will attempt to cut a new release earlier (however this is not guaranteed, and you are still welcome to point to a branch in NPM if we are unable to release on your timeline). + +--- + +The following section is unlikely to be useful to general contributors to Dynamoose, and is reserved for project maintainers. + +### Release + +In order to release a version of Dynamoose you can kick off this process by running `node publish`. This will kick off the release process. Following the steps it guides you through should lead to a successful release. Please [contact me](https://charlie.fish/contact) or message me on the Dynamoose Slack (Charlie Fish) if you have questions or run into any issues. + +It is important to note that you must have write permissions to the `master` branch in order for this process to be successful. From 45cf2c3e14e5969af2b31319ed7b32c159547b89 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 22:05:18 -0600 Subject: [PATCH 16/20] Adding support for deploying to more sites --- .github/workflows/publish.yml | 5 +++-- publish/information/retrieve.js | 13 ++++++++++++- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index e8c16d325..cbbced2c2 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -9,6 +9,7 @@ jobs: runs-on: ubuntu-latest outputs: npmtag: ${{ steps.data.outputs.npmtag }} + websites3bucket: ${{ steps.data.outputs.websites3bucket }} steps: - uses: actions/checkout@v2 - run: npm i @@ -50,7 +51,7 @@ jobs: publishsite: needs: getinfo runs-on: ubuntu-latest - if: needs.getinfo.outputs.npmtag == 'latest' + if: needs.getinfo.outputs.websites3bucket != '' steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v1 @@ -60,7 +61,7 @@ jobs: with: args: --follow-symlinks --delete --cache-control 's-maxage=604800, max-age=0' env: - AWS_S3_BUCKET: ${{ secrets.AWS_SITE_S3_BUCKET }} + AWS_S3_BUCKET: ${{ needs.getinfo.outputs.websites3bucket }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_REGION: 'us-west-2' diff --git a/publish/information/retrieve.js b/publish/information/retrieve.js index 9b5bb9778..efda7a198 100644 --- a/publish/information/retrieve.js +++ b/publish/information/retrieve.js @@ -1,11 +1,22 @@ module.exports = (version) => { const regex = /^v?((?:\d\.?){1,3})(?:-(.*)\.(\d*))?$/gmu; const [,main,tag,tagNumber] = regex.exec(version); - return { + const obj = { main, tag, "npmtag": tag || "latest", tagNumber, "isPrerelease": Boolean(tag) }; + + switch(obj.npmtag) { + case "latest": + obj.websites3bucket = "dynamoosejs.com"; + break; + default: + obj.websites3bucket = ""; + break; + } + + return obj; }; From 1f42c65dd066a8c4b3dc501cf9eb2f3c2603650b Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 22:10:15 -0600 Subject: [PATCH 17/20] Checking out original branch and deleting version branch after deployment --- publish/index.js | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/publish/index.js b/publish/index.js index 0d68b66a6..d3279cc33 100644 --- a/publish/index.js +++ b/publish/index.js @@ -28,13 +28,14 @@ let package = require("../package.json"); console.error("Exiting.\n"); process.exit(1); } + const originalBranch = (await git.status()).current; let results = await inquirer.prompt([ { "name": "branch", "type": "list", "message": "What branch would you like to publish?", "choices": (await git.branchLocal()).all, - "default": (await git.status()).current + "default": originalBranch } ]); await git.checkout(results.branch); @@ -154,6 +155,13 @@ let package = require("../package.json"); const npmPoll = ora("Polling NPM for release").start(); await isReleaseSubmiitted(results.version); npmPoll.succeed("Version successfully published to NPM"); + // Restore Git to original state + const gitCheckoutOriginal = ora(`Checking out ${originalBranch} branch`).start(); + await git.checkout(originalBranch); + gitCheckoutOriginal.succeed(`Checked out ${originalBranch} branch`); + const gitDeleteNewBranch = ora(`Deleting ${branch} branch`).start(); + await git.deleteLocalBranch(branch); + gitDeleteNewBranch.succeed(`Deleted ${branch} branch`); // Complete process.exit(0); })(); From a05c0608c8279b1b0014c146f70e64ef5e19ae14 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 22:11:31 -0600 Subject: [PATCH 18/20] Fixing function name typo --- publish/index.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/publish/index.js b/publish/index.js index d3279cc33..5bcbcaef6 100644 --- a/publish/index.js +++ b/publish/index.js @@ -153,7 +153,7 @@ let package = require("../package.json"); gitRelease.succeed("GitHub release created"); // Poll NPM for release const npmPoll = ora("Polling NPM for release").start(); - await isReleaseSubmiitted(results.version); + await isReleaseSubmitted(results.version); npmPoll.succeed("Version successfully published to NPM"); // Restore Git to original state const gitCheckoutOriginal = ora(`Checking out ${originalBranch} branch`).start(); @@ -191,11 +191,11 @@ async function isPRMerged(pr) { await utils.timeout(5000); } while (!data.merged); } -async function isReleaseSubmiitted(release) { +async function isReleaseSubmitted(release) { try { await npmFetch(`/dynamoose/${release}`); } catch (e) { await utils.timeout(5000); - isReleaseSubmiitted(release); + isReleaseSubmitted(release); } } From 032bb2578066b8e8f613487af82fe80ed59a9e8a Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 22:19:51 -0600 Subject: [PATCH 19/20] Fixing issues with polling for NPM release --- publish/index.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/publish/index.js b/publish/index.js index 5bcbcaef6..f726a52de 100644 --- a/publish/index.js +++ b/publish/index.js @@ -193,9 +193,9 @@ async function isPRMerged(pr) { } async function isReleaseSubmitted(release) { try { - await npmFetch(`/dynamoose/${release}`); + await npmFetch(`/dynamoose/${release.substring(1)}`); } catch (e) { await utils.timeout(5000); - isReleaseSubmitted(release); + return isReleaseSubmitted(release); } } From ed20baf601a4c83a62d8e3e2a36cb5c592920610 Mon Sep 17 00:00:00 2001 From: Charlie Fish Date: Wed, 22 Apr 2020 22:24:28 -0600 Subject: [PATCH 20/20] Adding support for custom text editor when publishing --- publish/index.js | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/publish/index.js b/publish/index.js index f726a52de..1ffd5112d 100644 --- a/publish/index.js +++ b/publish/index.js @@ -56,6 +56,13 @@ let package = require("../package.json"); "message": "Is this version a prerelease version?", "default": (res) => retrieveInformation(res.version).isPrerelease }, + { + "name": "textEditor", + "type": "input", + "message": "What is the command line bin to launch your favorite text editor? (ex. `code`, `atom`, `nano`, etc.)", + "default": "code" // TODO: use default from Git preference, or take it from a user configuration file + // "validate": // TODO: ensure the command line thing exists and is valid (maybe by using `which` and checking to see if the output of that exists and is not `_____ not found`) + }, { "name": "confirm", "type": "confirm", @@ -105,7 +112,7 @@ let package = require("../package.json"); const changelogFilePath = path.join(os.tmpdir(), `${results.version}-changelog.md`); const changelogTemplate = `## ${versionFriendlyTitle}\n\n${await fs.readFile(path.join(__dirname, "CHANGELOG_TEMPLATE.md"), "utf8")}`; await fs.writeFile(changelogFilePath, changelogTemplate); - await exec(`code ${changelogFilePath}`); + await exec(`${results.textEditor} ${changelogFilePath}`); const pendingChangelogSpinner = ora("Waiting for user to finish changelog, press enter to continue.").start(); await keypress(); pendingChangelogSpinner.succeed("Finished changelog");