Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

General correction of language, style, and wrong links #436

Merged
merged 5 commits into from
Apr 28, 2023
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1 @@
node_modules/
node_modules/
safwansamsudeen marked this conversation as resolved.
Show resolved Hide resolved
30 changes: 16 additions & 14 deletions building/configlet/lint.md
Original file line number Diff line number Diff line change
Expand Up @@ -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%20Manual%20of%20Style:~:text=Guitar\).%5B3%5D-,Chicago%20Manual%20of%20Style,-%5Bedit%5D) of title case):
safwansamsudeen marked this conversation as resolved.
Show resolved Hide resolved
- 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`)
safwansamsudeen marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down
14 changes: 6 additions & 8 deletions building/github/contributors-pull-request-guide.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,39 @@
# 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.

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 two to three hours to review and can result in dozens of comments.
safwansamsudeen marked this conversation as resolved.
Show resolved Hide resolved
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.

Here are some recommendations to help streamline the process even more.
safwansamsudeen marked this conversation as resolved.
Show resolved Hide resolved

### Recommendation: read the documentation
### Read the documentation
safwansamsudeen marked this conversation as resolved.
Show resolved Hide resolved

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.
If so, please open a pull request to the exercise's metadata in the [problems-specifications repo][problem-specifications] instead.

## 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.
Expand Down
24 changes: 15 additions & 9 deletions building/github/gha-best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion building/github/maintainers-pull-request-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion building/tooling/analyzers/docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions building/tooling/analyzers/feedback-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
safwansamsudeen marked this conversation as resolved.
Show resolved Hide resolved

## Definitions

Expand Down