From 8afd6d2058761732a745ed00e5e4c7a19a208bbf Mon Sep 17 00:00:00 2001 From: Jeremy De La Cruz Date: Fri, 15 Oct 2021 15:48:14 -0400 Subject: [PATCH 1/7] Add docs about using an inclusive linter --- .../inclusive-linting.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/continuous-integration/inclusive-linting.md diff --git a/docs/continuous-integration/inclusive-linting.md b/docs/continuous-integration/inclusive-linting.md new file mode 100644 index 0000000000..8140e6c36c --- /dev/null +++ b/docs/continuous-integration/inclusive-linting.md @@ -0,0 +1,35 @@ +# Inclusive Linting + +As software professionals we should strive to promote an inclusive work environment, which naturally extends to the code we write. It's important to keep the use of inclusive language consistent across an entire project or repository. + +To achieve this, we recommend using a text file analysis tool such as an inclusive linter and including this as a step in your CI pipelines. + +## What to Lint for + +The primary goal of an inclusive linter is to flag any occurrences of non-inclusive language within source code (and optionally suggest some alternatives). Non-inclusive words or phrases in a project can be found anywhere from comments and documentation to variable names. + +An inclusive linter may include its own dictionary of "default" non-inclusive words and phrases to run against as a good starting point. These tools can also be customizable, oftentimes offering the ability to omit some terms and/or add your own. + +The ability to add additional terms to your linter has the added benefit of enabling linting of sensitive language on top of inclusive linting. This can prevent things such as customer names or other non-public information from making it into your git history, for instance. + +## Getting Started with an Inclusive Linter + +### [`woke`] + +One inclusive linter we recommend is `woke`. It is a language-agnostic CLI tool that detects non-inclusive language in your source code and recommends alternatives. While it has a default ruleset, you can customize it and/or define your own ruleset yaml file to be run against. + +Running the tool locally is relatively straightforward: + +```sh +$ woke test.txt + +test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) +* Blacklist + ^ +``` + +It can be run locally on your machine or on a CI/CD system, even being offered as a [GitHub Action]. More information about configuration and usage is available in the `woke` [docs]. + +[`woke`]: (https://github.com/get-woke/woke) +[GitHub Action]: (https://github.com/marketplace/actions/run-woke) +[docs]: (https://docs.getwoke.tech/) From d7685765b4b995a8fa6f6d00382b650f8d9bd645 Mon Sep 17 00:00:00 2001 From: Jeremy De La Cruz Date: Mon, 18 Oct 2021 10:55:14 -0400 Subject: [PATCH 2/7] Address markdown lint errors --- docs/continuous-integration/inclusive-linting.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/continuous-integration/inclusive-linting.md b/docs/continuous-integration/inclusive-linting.md index 8140e6c36c..e8ec69e618 100644 --- a/docs/continuous-integration/inclusive-linting.md +++ b/docs/continuous-integration/inclusive-linting.md @@ -1,6 +1,6 @@ # Inclusive Linting -As software professionals we should strive to promote an inclusive work environment, which naturally extends to the code we write. It's important to keep the use of inclusive language consistent across an entire project or repository. +As software professionals we should strive to promote an inclusive work environment, which naturally extends to the code we write. It's important to keep the use of inclusive language consistent across an entire project or repository. To achieve this, we recommend using a text file analysis tool such as an inclusive linter and including this as a step in your CI pipelines. @@ -16,7 +16,7 @@ The ability to add additional terms to your linter has the added benefit of enab ### [`woke`] -One inclusive linter we recommend is `woke`. It is a language-agnostic CLI tool that detects non-inclusive language in your source code and recommends alternatives. While it has a default ruleset, you can customize it and/or define your own ruleset yaml file to be run against. +One inclusive linter we recommend is `woke`. It is a language-agnostic CLI tool that detects non-inclusive language in your source code and recommends alternatives. While it has a default ruleset, you can customize it and/or define your own ruleset yaml file to be run against. Running the tool locally is relatively straightforward: @@ -30,6 +30,6 @@ test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` ins It can be run locally on your machine or on a CI/CD system, even being offered as a [GitHub Action]. More information about configuration and usage is available in the `woke` [docs]. -[`woke`]: (https://github.com/get-woke/woke) -[GitHub Action]: (https://github.com/marketplace/actions/run-woke) -[docs]: (https://docs.getwoke.tech/) +[`woke`]: https://github.com/get-woke/woke +[GitHub Action]: https://github.com/marketplace/actions/run-woke +[docs]: https://docs.getwoke.tech/ From 60b3260b9856a2042f07068d685b63d4a623e919 Mon Sep 17 00:00:00 2001 From: Jeremy De La Cruz Date: Mon, 18 Oct 2021 11:03:07 -0400 Subject: [PATCH 3/7] Improve clarity --- docs/continuous-integration/inclusive-linting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/continuous-integration/inclusive-linting.md b/docs/continuous-integration/inclusive-linting.md index e8ec69e618..ad2dbe61b3 100644 --- a/docs/continuous-integration/inclusive-linting.md +++ b/docs/continuous-integration/inclusive-linting.md @@ -28,7 +28,7 @@ test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` ins ^ ``` -It can be run locally on your machine or on a CI/CD system, even being offered as a [GitHub Action]. More information about configuration and usage is available in the `woke` [docs]. +`woke` can be run locally on your machine or CI/CD system and is also available as a [GitHub Action]. For more information about configuration and usage, see the official [docs]. [`woke`]: https://github.com/get-woke/woke [GitHub Action]: https://github.com/marketplace/actions/run-woke From baad44932342e4232946fc4fcdb44282bb5e6a4f Mon Sep 17 00:00:00 2001 From: Jeremy De La Cruz Date: Mon, 18 Oct 2021 14:49:40 -0400 Subject: [PATCH 4/7] Address PR comments --- docs/continuous-integration/inclusive-linting.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/continuous-integration/inclusive-linting.md b/docs/continuous-integration/inclusive-linting.md index ad2dbe61b3..dc230bf171 100644 --- a/docs/continuous-integration/inclusive-linting.md +++ b/docs/continuous-integration/inclusive-linting.md @@ -1,6 +1,6 @@ # Inclusive Linting -As software professionals we should strive to promote an inclusive work environment, which naturally extends to the code we write. It's important to keep the use of inclusive language consistent across an entire project or repository. +As software professionals we should strive to promote an inclusive work environment, which naturally extends to the code and documentation we write. It's important to keep the use of inclusive language consistent across an entire project or repository. To achieve this, we recommend using a text file analysis tool such as an inclusive linter and including this as a step in your CI pipelines. @@ -16,7 +16,7 @@ The ability to add additional terms to your linter has the added benefit of enab ### [`woke`] -One inclusive linter we recommend is `woke`. It is a language-agnostic CLI tool that detects non-inclusive language in your source code and recommends alternatives. While it has a default ruleset, you can customize it and/or define your own ruleset yaml file to be run against. +One inclusive linter we recommend is `woke`. It is a language-agnostic CLI tool that detects non-inclusive language in your source code and recommends alternatives. While `woke` automatically applies a [default ruleset] with non-inclusive terms to lint for, you can also apply a custom rule config (via a yaml file) with additional terms to lint for. See [`example.yaml`] for an example of adding custom rules. Running the tool locally is relatively straightforward: @@ -31,5 +31,7 @@ test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` ins `woke` can be run locally on your machine or CI/CD system and is also available as a [GitHub Action]. For more information about configuration and usage, see the official [docs]. [`woke`]: https://github.com/get-woke/woke +[default ruleset]: https://github.com/get-woke/woke/blob/main/pkg/rule/default.yaml +[`example.yaml`]: https://github.com/get-woke/woke/blob/main/example.yaml [GitHub Action]: https://github.com/marketplace/actions/run-woke [docs]: https://docs.getwoke.tech/ From bc3f1fdee16bbce6d27db65a783d981ba97e8aa9 Mon Sep 17 00:00:00 2001 From: Jeremy De La Cruz Date: Mon, 18 Oct 2021 16:31:12 -0400 Subject: [PATCH 5/7] Address PR comments --- docs/continuous-integration/inclusive-linting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/continuous-integration/inclusive-linting.md b/docs/continuous-integration/inclusive-linting.md index dc230bf171..b93c163349 100644 --- a/docs/continuous-integration/inclusive-linting.md +++ b/docs/continuous-integration/inclusive-linting.md @@ -23,8 +23,8 @@ Running the tool locally is relatively straightforward: ```sh $ woke test.txt -test.txt:2:2-11: `Blacklist` may be insensitive, use `denylist`, `blocklist` instead (warning) -* Blacklist +test.txt:2:2-11: `guys` may be insensitive, use `folks`, `people` instead (warning) +* guys ^ ``` From 4fad5ee370e5ccd185445f6eda373cc358e5d7e1 Mon Sep 17 00:00:00 2001 From: Jeremy De La Cruz Date: Tue, 19 Oct 2021 12:02:15 -0400 Subject: [PATCH 6/7] Address PR comments and add link to inclusive linting section in main CI guidance page --- docs/continuous-integration/README.md | 1 + .../inclusive-linting.md | 34 +++++++++++++++++-- 2 files changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/continuous-integration/README.md b/docs/continuous-integration/README.md index be2887d9ee..02a6c18afd 100644 --- a/docs/continuous-integration/README.md +++ b/docs/continuous-integration/README.md @@ -39,6 +39,7 @@ An automated build should encompass the following principles: - [ ] **Code Style Checks** - Code across an engineering team must be formatted to agreed coding standards. Such standards keep code consistent, and most importantly easy for the team and customer(s) to read and refactor. Code styling consistency encourages collective ownership for project scrum teams and our partners. - There are several open source code style validation tools available to choose from ([code style checks](https://github.com/checkstyle/checkstyle), [StyleCop](https://en.wikipedia.org/wiki/StyleCop)). The [Code Review section](../code-reviews/README.md#language-specific-guidance) of the playbook has suggestions for linters and preferred styles for a number of languages. + - Your code and documentation should avoid the use of non-inclusive language wherever possible. Follow the [Inclusive Linting section](inclusive-linting.md) to ensure your project promotes an inclusive work environment for both the team and for customers. - We recommend incorporating security analysis tools within the build stage of your pipeline such as: code credential scanner, security risk detection, static analysis, etc. For Azure DevOPS, you can add a security scan task to your pipeline by installing the [Microsoft Security Code Analysis Extension](https://secdevtools.azurewebsites.net/#pills-onboard). GitHub Actions supports a similar extension with the [RIPS security scan solution](https://github.com/marketplace/actions/rips-security-scan). - Code standards are maintained within a single configuration file. There should be a step in your build pipeline that asserts code in the latest commit conforms to the known style definition. - [ ] **Build Script Target** diff --git a/docs/continuous-integration/inclusive-linting.md b/docs/continuous-integration/inclusive-linting.md index b93c163349..ef17646de6 100644 --- a/docs/continuous-integration/inclusive-linting.md +++ b/docs/continuous-integration/inclusive-linting.md @@ -18,17 +18,45 @@ The ability to add additional terms to your linter has the added benefit of enab One inclusive linter we recommend is `woke`. It is a language-agnostic CLI tool that detects non-inclusive language in your source code and recommends alternatives. While `woke` automatically applies a [default ruleset] with non-inclusive terms to lint for, you can also apply a custom rule config (via a yaml file) with additional terms to lint for. See [`example.yaml`] for an example of adding custom rules. -Running the tool locally is relatively straightforward: +Running the tool locally on a file or directory is relatively straightforward: ```sh $ woke test.txt -test.txt:2:2-11: `guys` may be insensitive, use `folks`, `people` instead (warning) +test.txt:2:2-6: `guys` may be insensitive, use `folks`, `people` instead (warning) * guys ^ ``` -`woke` can be run locally on your machine or CI/CD system and is also available as a [GitHub Action]. For more information about configuration and usage, see the official [docs]. +`woke` can be run locally on your machine or CI/CD system via CLI and is also available as a [GitHub Action]. + +To use the GitHub Action with the default ruleset in a CI pipeline: + +1. Add the `woke` action as a step in your project's CI pipeline yaml: + + ```yaml + name: ci + on: + - pull_request + jobs: + woke: + name: woke + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + + - name: woke + uses: get-woke/woke-action@v0 + with: + # Cause the check to fail on any broke rules + fail-on-error: true + ``` + +1. Run your pipeline +1. View the output in the "Actions" tab in the main repository view + +For more information about additional configuration and usage, see the official [docs]. [`woke`]: https://github.com/get-woke/woke [default ruleset]: https://github.com/get-woke/woke/blob/main/pkg/rule/default.yaml From 6a24670b6d30acb72e578a527b70f329882abf01 Mon Sep 17 00:00:00 2001 From: Jeremy De La Cruz Date: Tue, 19 Oct 2021 14:21:33 -0400 Subject: [PATCH 7/7] Add link to woke action with reviewdog --- docs/continuous-integration/inclusive-linting.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/continuous-integration/inclusive-linting.md b/docs/continuous-integration/inclusive-linting.md index ef17646de6..1e4cb52194 100644 --- a/docs/continuous-integration/inclusive-linting.md +++ b/docs/continuous-integration/inclusive-linting.md @@ -28,9 +28,12 @@ test.txt:2:2-6: `guys` may be insensitive, use `folks`, `people` instead (warnin ^ ``` -`woke` can be run locally on your machine or CI/CD system via CLI and is also available as a [GitHub Action]. +`woke` can be run locally on your machine or CI/CD system via CLI and is also available as a two GitHub Actions: -To use the GitHub Action with the default ruleset in a CI pipeline: +- [Run woke] +- [Run woke with Reviewdog] + +To use the standard "Run woke" GitHub Action with the default ruleset in a CI pipeline: 1. Add the `woke` action as a step in your project's CI pipeline yaml: @@ -61,5 +64,6 @@ For more information about additional configuration and usage, see the official [`woke`]: https://github.com/get-woke/woke [default ruleset]: https://github.com/get-woke/woke/blob/main/pkg/rule/default.yaml [`example.yaml`]: https://github.com/get-woke/woke/blob/main/example.yaml -[GitHub Action]: https://github.com/marketplace/actions/run-woke +[Run woke]: https://github.com/marketplace/actions/run-woke +[Run woke with reviewdog]: https://github.com/marketplace/actions/run-woke-with-reviewdog [docs]: https://docs.getwoke.tech/