From 53a6f3bd50d5b9e5bf221e990f601dfdc720e340 Mon Sep 17 00:00:00 2001 From: Nick Alteen Date: Fri, 26 Jan 2024 13:55:40 -0500 Subject: [PATCH] Format CONTRIBUTING.md --- .github/CONTRIBUTING.md | 113 ++++++++++++++++++++++++++++------------ 1 file changed, 80 insertions(+), 33 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fa05ba3e..dbc4063e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,59 +1,106 @@ # Contributions -We welcome contributions in the form of issues and pull requests. We view the contributions and process as the same for internal and external contributors. +We welcome contributions in the form of issues and pull requests. We view the contributions and process as the same for internal and external contributors. ## Issues -Log issues for both bugs and enhancement requests. Logging issues are important for the open community. +Log issues for both bugs and enhancement requests. Logging issues are important for the open community. -Issues in this repository should be for the toolkit packages. General feedback for GitHub Actions should be filed in the [community forums.](https://github.community/t5/GitHub-Actions/bd-p/actions) Runner specific issues can be filed [in the runner repository](https://github.com/actions/runner). +Issues in this repository should be for the toolkit packages. General feedback for GitHub Actions should be filed in the [community discussions](https://github.com/orgs/community/discussions/). Runner-specific issues can be filed in the [GitHub Actions runner repository](https://github.com/actions/runner). ## Enhancements and Feature Requests -We ask that before significant effort is put into code changes, that we have agreement on taking the change before time is invested in code changes. +We ask that, before significant time or effort is put into code changes, we have agreement on the change itself. -1. Create a feature request. -2. When we agree to take the enhancement, create an ADR to agree on the details of the change. +1. Create a feature request. +1. When we agree to take the enhancement, create an Architectural Decision Record (ADR) to agree on the details of the change. -An ADR is an Architectural Decision Record. This allows consensus on the direction forward and also serves as a record of the change and motivation. [Read more here](../docs/adrs/README.md). +An ADR provides consensus on the direction forward and also serves as a record of the change and motivation. [Read more here](../docs/adrs/README.md). -## Development Life Cycle +## Development Lifecycle This repository uses [Lerna](https://github.com/lerna/lerna#readme) to manage multiple packages. Read the documentation there to begin contributing. -Note that before a PR will be accepted, you must ensure: -- all tests are passing -- `npm run format` reports no issues -- `npm run lint` reports no issues +> [!NOTE] +> +> Before a PR will be accepted, you must ensure: +> +> - All tests are passing +> - `npm run format` reports no issues +> - `npm run lint` reports no issues ### Useful Scripts -- `npm run bootstrap` This runs `lerna exec -- npm install` which will install dependencies in this repository's packages and cross-link packages where necessary. -- `npm run build` This compiles TypeScript code in each package (this is especially important if one package relies on changes in another when you're running tests). This is just an alias for `lerna run tsc`. -- `npm run format` This checks that formatting has been applied with Prettier. -- `npm test` This runs all Jest tests in all packages in this repository. - - If you need to run tests for only one package, you can pass normal Jest CLI options: - ```console - $ npm test -- packages/toolkit - ``` -- `npm run create-package [name]` This runs a script that automates a couple of parts of creating a new package. +- Install dependencies in this repository's packages and cross-link packages where necessary (runs `lerna exec -- npm install`) + + ```bash + npm run bootstrap + ``` + +- Compile the TypeScript code in each package (alias for `lerna run tsc`) + + > This is especially important if one package relies on changes in another. + + ```bash + npm run build + ``` + +- Check that formatting complies with this repository's [Prettier configuration](../.prettierrc.json) + + ```bash + # Check formatting + npm run format-check + + # Apply formatting + npm run format + ``` + +- Run Jest tests in all packages in this repository + + ```bash + npm test + ``` + +- Run Jest tests for a specific package in this repository + + ```console + npm test -- packages/toolkit + ``` + +- Automate initial setup of a new package (see [Creating a Package](#creating-a-package)) + + ```bash + npm run create-package [name] + ``` ### Creating a Package -1. In a new branch, create a new Lerna package: +1. Create a new branch -```console -$ npm run create-package new-package -``` + ```bash + git checkout -b + ``` -This will ask you some questions about the new package. Start with `0.0.0` as the first version (look generally at some of the other packages for how the package.json is structured). +1. Create a new Lerna package -2. Add `tsc` script to the new package's package.json file: + ```bash + npm run create-package + ``` -```json -"scripts": { - "tsc": "tsc" -} -``` + This will ask you some questions about the new package. -3. Start developing 😄. + - Start with `0.0.0` as the first version. + - Look generally at some of the other packages for how the `package.json` is structured. + +1. Add the `tsc` script to the new package's `package.json` file: + + ```json + { + // ... + "scripts": { + "tsc": "tsc" + } + } + ``` + +1. Start developing 😄