diff --git a/building/configlet/lint.md b/building/configlet/lint.md index 8176f7ac..07affb2a 100644 --- a/building/configlet/lint.md +++ b/building/configlet/lint.md @@ -526,24 +526,26 @@ The `config.json` file should have the following checks: ## Glossary -1. Non-blank string: a string that contains at least one non-whitespace character. -2. kebab-case string: a string that contains only characters in the range `[a-z0-9]`, optionally separated by dashes (e.g. "two-fer"). It must match the regular expression: `^[a-z0-9]+(-[a-z0-9]+)*$` -3. Title Case string: a non-blank string that follows the below guidelines (from the Chicago Manual of Style, see https://en.wikipedia.org/wiki/Title_case): - > - Capitalize the first and last words of titles and subtitles. - > - Capitalize "major" words (nouns, pronouns, verbs, adjectives, adverbs, and some conjunctions). - > - Lowercase the conjunctions _and_, _but_, _for_, _or_, and _nor_. - > - Lowercase the articles _the_, _a_, and _an_. - > - Lowercase prepositions, regardless of length, except when they are stressed, are used adverbially or adjectivally, or are used as conjunctions. - > - Lowercase the words _to_ and _as_. - > - Lowercase the second part of Latin species names. -4. Sentence Case string: a non-blank string that follows the below guidelines (see https://en.wikipedia.org/wiki/Letter_case#Sentence_case): - > - Capitalize the first word of the sentence, as well as proper nouns and other words as required by a more specific rule. -5. Valid `"files"` pattern: A non-blank string¹ that specifies a location of a file used in an exercise, relative to the exercise's directory. A pattern may use one of the following placeholders: +1. **Non-blank string**: a string that contains at least one non-whitespace character. +2. **kebab-case string**: a string that contains only characters in the range `[a-z0-9]`, optionally separated by dashes (e.g. "two-fer"). It must match the regular expression: `^[a-z0-9]+(-[a-z0-9]+)*$` +3. **Title Case string**: a non-blank string that follows the below [guidelines from the Chicago Manual of Style](https://en.wikipedia.org/wiki/Title_case#Chicago_Manual_of_Style): + - Capitalize the first and last words of titles and subtitles. + - Capitalize "major" words (nouns, pronouns, verbs, adjectives, adverbs, and some conjunctions). + - Lowercase the conjunctions _and_, _but_, _for_, _or_, and _nor_. + - Lowercase the articles _the_, _a_, and _an_. + - Lowercase prepositions, regardless of length, except when they are stressed, are used adverbially or adjectivally, or are used as conjunctions. + - Lowercase the words _to_ and _as_. + - Lowercase the second part of Latin species names. +4. **Sentence Case string**: a non-blank string that follows the below [guidelines](https://en.wikipedia.org/wiki/Letter_case#Sentence_case): + - Capitalize the first word of the sentence, as well as proper nouns and other words as required by a more specific rule. +5. **Valid `files` pattern**: A non-blank string¹ that specifies a location of a file used in an exercise, relative to the exercise's directory. A pattern may use one of the following placeholders: + - `%{kebab_slug}`: the `kebab-case` exercise slug (e.g. `bit-manipulation`) - `%{snake_slug}`: the `snake_case` exercise slug (e.g. `bit_manipulation`) - `%{camel_slug}`: the `camelCase` exercise slug (e.g. `bitManipulation`) - `%{pascal_slug}`: the `PascalCase` exercise slug (e.g. `BitManipulation`) -6. Unique version 4 UUID string: A string that satisfies all of these conditions: +6. **Unique version 4 UUID string**: A string that satisfies all of these conditions: + - It only exists once in the track-level `config.json` file of a given Exercism track - It does not exist in the track-level `config.json` file of any other Exercism track - It does not exist in any `canonical-data.json` file in https://github.com/exercism/problem-specifications diff --git a/building/github/contributors-pull-request-guide.md b/building/github/contributors-pull-request-guide.md index fd3075a6..b1512eb3 100644 --- a/building/github/contributors-pull-request-guide.md +++ b/building/github/contributors-pull-request-guide.md @@ -1,33 +1,34 @@ # The Contributors' Guide to Pull Requests Thank you for wanting to contribute to Exercism! -Before creating a pull request, please read the [how to make a great Pull Request][how-to-make-a-great-pr] guide which aims to help you with the non-technical side of pull requests so that you have a great experience and help our maintaining team at the same time. +Before creating a pull request, please read the [how to make a great pull request][how-to-make-a-great-pr] guide which aims to help you with the non-technical side of pull requests so that you have a great experience and help our maintaining team at the same time. This documents contains some additional, Exercism-specific guidelines for different types of pull requests. ## Exercise Pull Requests Creating a pull request for a Concept Exercise or Practice Exercise can be daunting with the many rules around these types of exercises. -For this reason, it can take a maintainer 2 to 3 hours to review and can result in dozens of comments. - +For this reason, it can take a maintainer two to three hours to review and can result in dozens of comments. To help you, there'll be one primary reviewer commenting on your pull request. Don't be discouraged by the number of review comments; it is perfectly normal for an exercise to go through several rewrites before arriving at something both you and the primary reviewer are happy with. +## Recommendations + Here are some recommendations to help streamline the process even more. -### Recommendation: read the documentation +### Read the documentation Before creating a pull request for an exercise, be sure to read the [concept exercise documentation][concept-exercises] respectively [practice exercise documentation][practice-exercises]. Reading the documentation beforehand helps immensely, as reviews will have less comments and your pull request will be merged much sooner. -### Recommendation: examine existing exercises (if any) +### Examine existing exercises (if any) If the track has any existing exercises, take the time to study them a bit to discover what they look like and how they're structured. ## Practice Exercise Pull Requests -### Recommendation: consider whether the change actually belongs in problems-specifications +### Consider whether the change actually belongs in problems-specifications Some of the contents of a Practice Exercise (such as its introduction) comes from its (shared) metadata as defined in the [problems-specifications repo][problem-specifications]. If you're intending to update such content, consider whether the change might benefit other tracks too. @@ -35,7 +36,7 @@ If so, please open a pull request to the exercise's metadata in the [problems-sp ## General recommendations -### Recommendation: refrain from doing unsolicited reviews +### Refrain from doing unsolicited reviews All pull request reviews are done by one (or more) maintainers of the track, as they are responsible for signing off all changes to the repository. Maintainers doing the review also helps to avoid conflicting feedback for the pull request author. diff --git a/building/github/gha-best-practices.md b/building/github/gha-best-practices.md index fbba15ae..84b895f1 100644 --- a/building/github/gha-best-practices.md +++ b/building/github/gha-best-practices.md @@ -3,15 +3,21 @@ This _working_ document serves as a collection of best practices for making use of GitHub Actions. If you have any suggestions or additions, [please open a pull request on GitHub!](https://github.com/exercism/docs/edit/main/building/github/gha-best-practices.md) -- [Collection of Best Practices](#collection-of-best-practices) - - [Set timeouts for workflows](#set-timeouts-for-workflows) - - [Consider if (third-party) actions are really needed](#consider-if-third-party-actions-are-really-needed) - - [Limit scope of workflow token](#limit-scope-of-workflow-token) - - [Pin actions to SHAs](#pin-actions-to-shas) - - [Consider setting up a concurrency strategy](#consider-setting-up-a-concurrency-strategy) - - [Consider which triggers are really needed](#consider-which-triggers-are-really-needed) - - [Read the "Security hardening for GitHub Actions" guide](#read-the-security-hardening-for-github-actions-guide) -- [Workflow Checklist](#workflow-checklist) +- [GitHub Actions: Best Practices](#github-actions-best-practices) + - [Collection of Best Practices](#collection-of-best-practices) + - [Set timeouts for workflows](#set-timeouts-for-workflows) + - [Example](#example) + - [Consider if (third-party) actions are really needed](#consider-if-third-party-actions-are-really-needed) + - [Limit scope of workflow token](#limit-scope-of-workflow-token) + - [Example](#example-1) + - [Pin actions to SHAs](#pin-actions-to-shas) + - [Finding the commit SHA](#finding-the-commit-sha) + - [Example](#example-2) + - [Consider setting up a concurrency strategy](#consider-setting-up-a-concurrency-strategy) + - [Example](#example-3) + - [Consider which triggers are really needed](#consider-which-triggers-are-really-needed) + - [Read the "Security hardening for GitHub Actions" guide](#read-the-security-hardening-for-github-actions-guide) + - [Workflow Checklist](#workflow-checklist) ## Collection of Best Practices diff --git a/building/github/maintainers-pull-request-guide.md b/building/github/maintainers-pull-request-guide.md index 4e4c8a1c..0a29651b 100644 --- a/building/github/maintainers-pull-request-guide.md +++ b/building/github/maintainers-pull-request-guide.md @@ -6,7 +6,7 @@ This document contains some Exercism-specific pull request review guidelines. ## Reviewing Exercise Pull Requests Reviewing a pull request for a Concept Exercise or Practice Exercise can be daunting with the many rules around these types of exercise. -For this reason, a first-pass review by a maintainer often take 2 to 3 hours and results in dozens of comments. +For this reason, a first-pass review by a maintainer often takes two to three hours and results in dozens of comments. For Concept Exercises, there are also files with similar goals/contents (e.g. the exercise and concept introduction), where focusing on getting one of those perfect first is essential before branching out too far. To help streamline this workflow, we've developed the following recommendations. diff --git a/building/tooling/analyzers/docker.md b/building/tooling/analyzers/docker.md index c6872b83..71a357a0 100644 --- a/building/tooling/analyzers/docker.md +++ b/building/tooling/analyzers/docker.md @@ -2,7 +2,7 @@ Our Analyzers are deployed as Docker images. -Please read the [general Tooling docker information](/docs/building/tooling/analyzers/docker) to familiarize yourself with how these work. +Please read the [general tooling Docker information](/docs/building/tooling/docker) to familiarize yourself with how these work. When we run the Analyzer's container we execute a `run.sh` script. To ensure this works properly the following rules must be following: diff --git a/building/tooling/analyzers/feedback-guidelines.md b/building/tooling/analyzers/feedback-guidelines.md index bb9dd2df..232af7d7 100644 --- a/building/tooling/analyzers/feedback-guidelines.md +++ b/building/tooling/analyzers/feedback-guidelines.md @@ -4,8 +4,8 @@ _NOTE: This spec is currently being updated._ The goal of a language track on Exercism is to give people a way to achieve a high level of [fluency](/docs/using/product/fluency) at a low level of proficiency. We're aiming for fluency -in the syntax, idioms, and the standard library of the language. You can read -more about the [goal of exercism here](https://github.com/exercism/docs/blob/master/about/goal-of-exercism.md). +in the syntax, idioms, and the standard library of the language. Read +more about the [goal of Exercism here](https://github.com/exercism/docs/blob/master/about/goal-of-exercism.md). ## Definitions