diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..6b05fb01 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,30 @@ +# Contributing + +We genuinely appreciate folks who are trying to help out by lowering the barrier to understanding Node.js 🤗 + +Our baseline for all contributions is following the project's [Code of Conduct](./CODE_OF_CONDUCT.md). + +## Contributing New Examples + +If you'd like to contribute an example, we'd genuinely appreciate your help. There's a few things we'll expect from any contribution of a new example: + +- New examples should **probably** fit within the existing categories. + - If there's an example you'd like to make that _doesn't_ fit into a category, please don't hesitate to create an issue to suggest a broad category that it _would_ fit within. +- Usable example code. This means: + - Comprehensive comments. + - Descriptive and readable variable names. + - Modern JavaScript. +- Jest for testing. Examples' tests should check these boxes: + - Tests should be written for all code that can be tested. + - Tests should be in the format of `.test.js` and should live alongside the files they're testing. +- Proper documentation. This means: + - A README.md that explains what the example does and how to use it, plus documents the examples dependencies. + - The README should include a title, description, instructions for usage, and instructions for running the test. + +## Contributing to Tests + +We're always willing to take on more tests or improvements to our existing tests. We use Jest as our test tooling at present. + +## Contributing to Prose + +This repository has a non-trivial amount of written content. If you're interested in helping provide clarity and context or otherwise improving our prose, we welcome your contributions. diff --git a/README.md b/README.md index cc3800ee..de353754 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This repository is structured in a specific way: - **Second-level directories** are **project directories** named after specific modules, frameworks, platforms, or tools - for example, `yargs` is a CLI framework, both `express` and `fastify` are web frameworks, and `moment` is a utility. - **Third-level directories** are **example directories**, where specific examples live. You can find a full list of these examples in the [Examples](#examples) section below. -Here is an example of the structure: +Here is an example of the structure in general terms: ```text - examples (root) @@ -51,35 +51,7 @@ Command Line Interfaces (CLIs) are tools that can be accessed exclusively from t ## Contributing -We genuinely appreciate folks who are trying to help out by lowering the barrier to understanding Node.js 🤗 - -Our baseline for all contributions is following the project's [Code of Conduct](./CODE_OF_CONDUCT.md). - -### Contributing New Examples - -If you'd like to contribute an example, we'd genuinely appreciate your help. There's a few things we'll expect from any contribution of a new example: - -- If the example is of a new category or project, the appropriate new directories should be created in addition to the necessary example directory. This means: - - If someone wanted to contribute an `express` example and there was no top level category that it fit within, creating a `servers` directory with an `express` subdirectory would be needed. - - If someone wanted to create `fastify` example after the `servers` directory had already been created, creating a `fastify` directory within the `servers` category would be needed. -- Usable example code. This means: - - Comprehensive comments. - - Descriptive and readable variable names. - - Modern JavaScript. -- We use Jest for testing. Examples' tests should check these boxes: - - Tests should be written for all code that can be tested. - - Tests should be in the format of `.test.js` and should live alongside the files they're testing. -- Proper documentation. This means: - - A README.md that explains what the example does and how to use it, plus documents the examples dependencies. - - The README should include a title, description, instructions for usage, and instructions for running the test. - -### Contributing to Tests - -We're always willing to take on more tests or improvements to our existing tests. We use Jest, and actively leverage the `onlyChanged` flag to reduce nosie in our CI. - -### Contributing to Prose - -This repository has a non-trivial amount of written content. If you're interested in helping provide clarity and context or otherwise improving our prose, we welcome your contributions. +We've documented how to meaningfully contribute in [CONTRIBUTING.md](./CONTRIBUTING.md) 🤗 ### Thank You To Our Contributors diff --git a/applications/README.md b/applications/README.md new file mode 100644 index 00000000..14900b08 --- /dev/null +++ b/applications/README.md @@ -0,0 +1,11 @@ +# Node.js Examples: Applications + +In this directory, we have examples of Applications that are built with or extensively leverage Node.js. See the [Examples section](../README.md#examples) of the root [README.md](../README.md) for a list of all projects contained within, or take a look through the directories yourself. + +## What is an Application in the context of nodejs/examples + +Anything that can be considered a standalone application. For example: + +- Desktop applications that bundle or otherwise use Node.js +- Mobile applications that leverage Node.js +- Other bundled applications that can be run as a standalone executable diff --git a/cli/README.md b/cli/README.md index f3a891c5..b973cc05 100644 --- a/cli/README.md +++ b/cli/README.md @@ -1,3 +1,7 @@ # Node.js Examples: CLI In this directory, we have examples of Command Line Interfaces (CLIs) built with Node.js. See the [Examples section](../README.md#examples) of the root [README.md](../README.md) for a list of all projects contained within, or take a look through the directories yourself. + +## What is a CLI in the context of nodejs/examples + +Anything that can be considered a command-line interface, built with Node.js. diff --git a/cloud/README.md b/cloud/README.md new file mode 100644 index 00000000..87231a0b --- /dev/null +++ b/cloud/README.md @@ -0,0 +1,13 @@ +# Node.js Examples: Cloud + +In this directory, we have examples of using Node.js with technologies that are related to the cloud. See the [Examples section](../README.md#examples) of the root [README.md](../README.md) for a list of all projects contained within, or take a look through the directories yourself. + +## What is Cloud in the context of nodejs/examples + +Anything that is related to deployment of Node.js applications to the cloud. For example: + +- Containers (Docker) +- Serverless (Serverless Framework, OpenFaaS, AWS Lambda, Google Cloud Functions, Google Cloud Run, Azure Functions) +- Orchestration (Kubernetes, Terraform, OpenShift) +- Cloud-specific (AWS, GCP, Azure, IBM Cloud, DigitalOcean, Alibaba Cloud, Oracle Cloud) +- Tiny Clouds (Netlify, Now, Glitch, CloudFlare Workers, Heroku, Surge, Begin) diff --git a/servers/README.md b/servers/README.md new file mode 100644 index 00000000..fdb9fafe --- /dev/null +++ b/servers/README.md @@ -0,0 +1,10 @@ +# Node.js Examples: Servers + +In this directory, we have examples of servers that are built with Node.js. See the [Examples section](../README.md#examples) of the root [README.md](../README.md) for a list of all projects contained within, or take a look through the directories yourself. + +## What is a Server in the context of nodejs/examples + +Any software built with Node.js that serves content over HTTP. For example: + +- An API server that responds with a JSON payload +- A web server that serves dynamic content based on user requests diff --git a/utilities/README.md b/utilities/README.md new file mode 100644 index 00000000..c1dbd2b9 --- /dev/null +++ b/utilities/README.md @@ -0,0 +1,10 @@ +# Node.js Examples: Utilities + +In this directory, we have examples of utilities that are useful for Node.js development. See the [Examples section](../README.md#examples) of the root [README.md](../README.md) for a list of all projects contained within, or take a look through the directories yourself. + +## What is a Utility in the context of nodejs/examples + +Any module that is helpful in simplifying tasks that you'll encounter in Node.js. For example: + +- Utility libraries (Lodash, Underscore) that help simplify common operations +- Single purpose libraries (Moment, node-fetch) that solve a problem particularly well