Skip to content

Commit bbb7548

Browse files
sanderploegsmasanderploegsma
authored
Lint markdown files (#2574)
1 parent c466cc7 commit bbb7548

File tree

77 files changed

+567
-623
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+567
-623
lines changed

‎.github/workflows/build.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Build
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
workflow_dispatch:
9+
10+
defaults:
11+
run:
12+
working-directory: exercises
13+
14+
jobs:
15+
build:
16+
name: Check if tests compile cleanly with starter sources
17+
runs-on: ubuntu-22.04
18+
steps:
19+
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
20+
- name: Set up JDK 1.17
21+
uses: actions/setup-java@0ab4596768b603586c0de567f2430c30f5b0d2b0
22+
with:
23+
java-version: 17
24+
distribution: "temurin"
25+
- name: Check if tests compile cleanly with starter sources
26+
run: ./gradlew compileStarterTestJava --continue

‎.github/workflows/gradle.yml ‎.github/workflows/lint.yml

+12-15
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Gradle
1+
name: Lint
22

33
on:
44
pull_request:
@@ -7,12 +7,12 @@ on:
77
- main
88
workflow_dispatch:
99

10-
defaults:
11-
run:
12-
working-directory: exercises
10+
permissions:
11+
contents: read
1312

1413
jobs:
15-
build:
14+
java:
15+
name: Lint Java files using Checkstyle
1616
runs-on: ubuntu-22.04
1717
steps:
1818
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
@@ -21,17 +21,14 @@ jobs:
2121
with:
2222
java-version: 17
2323
distribution: "temurin"
24-
- name: Check if tests compile cleanly with starter sources
25-
run: ./gradlew compileStarterTestJava --continue
24+
- name: Run checkstyle
25+
run: ./gradlew check --exclude-task test --continue
26+
working-directory: exercises
2627

27-
lint:
28+
markdown:
29+
name: Lint Markdown files
2830
runs-on: ubuntu-22.04
2931
steps:
3032
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
31-
- name: Set up JDK 1.17
32-
uses: actions/setup-java@0ab4596768b603586c0de567f2430c30f5b0d2b0
33-
with:
34-
java-version: 17
35-
distribution: "temurin"
36-
- name: Run checkstyle
37-
run: ./gradlew check --exclude-task test --continue
33+
- name: Lint markdown
34+
uses: DavidAnson/markdownlint-cli2-action@ed4dec634fd2ef689c7061d5647371d8248064f1

‎.github/workflows/test.yml

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ on:
99

1010
jobs:
1111
test:
12+
name: Test all exercises using java-test-runner
1213
runs-on: ubuntu-22.04
1314
steps:
1415
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11

‎.markdownlint-cli2.jsonc

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"globs": [
3+
"concepts/**/*.md",
4+
"docs/**/*.md",
5+
"exercises/**/*.md",
6+
"reference/**/*.md",
7+
"*.md"
8+
],
9+
"ignores": [
10+
// Deprecated exercises should never be updated
11+
"exercises/concept/blackjack/**/*.md",
12+
"exercises/practice/accumulate/**/*.md",
13+
"exercises/practice/beer-song/**/*.md",
14+
"exercises/practice/binary/**/*.md",
15+
"exercises/practice/diffie-hellman/**/*.md",
16+
"exercises/practice/hexadecimal/**/*.md",
17+
"exercises/practice/octal/**/*.md",
18+
"exercises/practice/strain/**/*.md",
19+
"exercises/practice/trinary/**/*.md"
20+
]
21+
}

‎.markdownlint.jsonc

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// Configuration is based on the Exercism Markdown specification, see:
2+
// https://exercism.org/docs/building/markdown/markdown
3+
//
4+
// For information on writing markdownlint configuration see:
5+
// https://github.com/DavidAnson/markdownlint/blob/main/README.md#optionsconfig
6+
{
7+
"MD004": {
8+
"style": "dash" // Prefer hyphens for unordered lists
9+
},
10+
"MD013": false, // Exercism tends to break lines at sentence ends rather than at a column limit
11+
"MD024": false, // The format for instructions.md requires repeated headings, e.g. "Task"
12+
"MD033": false, // Inline HTML is allowed when used sparingly
13+
"MD048": false // We want three backticks for codeblocks, but four tildes for special blocks.
14+
}

‎CONTRIBUTING.md

+9-3
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,15 @@ gradle compileStarterTestJava
102102
When you finished your changes and checked that all validations have passed, it's time to commit and push them to your fork:
103103

104104
```sh
105-
$ git add .
106-
$ git commit -m "(An intention-revealing commit message)"
107-
$ git push -u origin your-branch-name
105+
git add .
106+
```
107+
108+
```sh
109+
git commit -m "(An intention-revealing commit message)"
110+
```
111+
112+
```sh
113+
git push -u origin your-branch-name
108114
```
109115

110116
Then, open a Pull Request on the [exercism/java][track-repo] repository.

‎POLICIES.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ References: [[1](https://github.com/exercism/java/issues/395#issue-215734887)]
121121
### Name test class after class under test
122122
123123
> If you're testing a class called `SomeClassName` then your test class should be called `SomeClassNameTest`.
124-
124+
>
125125
> The exception to this is if the tests are split into several test classes where each test class tests different functionality. In that case each class should be named `SomeClassNameFunctionalityTest` where `Functionality` is the name of the functionality to be tested in that class. See the [clock exercise](https://github.com/exercism/java/tree/main/exercises/practice/clock) as an example.
126126
127127
References: [[1](https://github.com/exercism/java/issues/697)]
@@ -131,11 +131,11 @@ References: [[1](https://github.com/exercism/java/issues/697)]
131131
> According to the starter implementation policy, any exercise with difficulty 4 or lower should have starter implementation.
132132
> Any exercise with difficulty 5 or above will have no starter implementation (unless its signature is very complicated).
133133
> This could be confusing to users when tackling their first exercise with difficulty 5 when they are used to starter implementation being provided.
134-
134+
>
135135
> Therefore a hints.md file should be added to the .meta directory for every exercise with difficulty 5.
136136
> This file should explain what they need to do when there is no starter implementation.
137137
> The files should all be the same so you can copy it from any other exercise with difficulty 5, e.g. [flatten-array](https://github.com/exercism/java/tree/main/exercises/pratice/flatten-array/.meta/hints.md).
138-
138+
>
139139
> We add the file to every exercise with difficulty 5 because the structure of the track means that we don't know which exercise will be the first one without starter implementation that a user will be faced with.
140140
141141
References: [[1](https://github.com/exercism/java/issues/1075)]
@@ -154,14 +154,14 @@ References: [[1](https://github.com/exercism/java/issues/1389)]
154154
> When an error has occured or a method can't return anything, the canonical data will just mark that as `"expected": null`.
155155
> This is because error handling varies from language to language, so the canonical data is leaving it up to each language track to decide how to deal with those situations.
156156
> It doesn't mean that the method needs to return `null`.
157-
157+
>
158158
> In Java it's considered bad practice to return `null`.
159159
> If you return `null` then the user of the method has to remember to check for `null` and they have to look at the implementation of the method to find out that this is necessary.
160-
160+
>
161161
> It's considered best practice to deal with errors and unexpected circumstances by throwing exceptions.
162162
> If you throw an exception then you force the user to deal with the problem.
163163
> You can either define your own exception (see [the triangle exercise](https://github.com/exercism/java/blob/main/exercises/practice/triangle/.meta/src/reference/java/TriangleException.java) for an example) or use a predefined one (see [the collatz-conjecture exercise](https://github.com/exercism/java/blob/main/exercises/practice/collatz-conjecture/src/test/java/CollatzCalculatorTest.java) for an example).
164-
164+
>
165165
> Another option is to use [Optionals](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html).
166166
> This can be more suitable if the case you want to deal with isn't an exceptional occurence, but rather an expected scenario, e.g. a search method not finding what it was searching for.
167167
> See [the word-search exercise](https://github.com/exercism/java/blob/main/exercises/practice/word-search/src/test/java/WordSearcherTest.java) for an example where `Optional` is used.

‎README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Exercism Java Track
22

33
[![Configlet](https://github.com/exercism/java/actions/workflows/configlet.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/configlet.yml)
4-
[![Gradle](https://github.com/exercism/java/actions/workflows/gradle.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/gradle.yml)
4+
[![Lint](https://github.com/exercism/java/actions/workflows/lint.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/lint.yml)
5+
[![Build](https://github.com/exercism/java/actions/workflows/build.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/build.yml)
56
[![Test](https://github.com/exercism/java/actions/workflows/test.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/test.yml)
67

78
Source for Exercism Exercises in Java.

‎concepts/booleans/about.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Booleans in Java are represented by the `boolean` type, which values can be either `true` or `false`.
44

5-
Java supports three [boolean operators][operators]:
5+
Java supports three [boolean operators][operators]:
66

77
- `!` (NOT): negates the boolean
88
- `&&` (AND): takes two booleans and results in true if they're both true

‎concepts/booleans/introduction.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Java supports three boolean operators:
88
- `&&` (AND): takes two booleans and results in true if they're both true
99
- `||` (OR): results in true if any of the two booleans is true
1010

11-
**Examples**
11+
## Examples
1212

1313
```java
1414
!true // => false

‎concepts/exceptions/about.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -112,23 +112,23 @@ public class ATM {
112112

113113
In this example, when no exception is thrown, the following is printed:
114114

115-
```
115+
```text
116116
Withdrawing 10.0
117117
Withdrawal succeeded
118118
Current balance: 5.0
119119
```
120120

121121
However, should the `bankAccount.withdraw(amount)` statement throw an `InsufficientBalanceException`, the following is printed:
122122

123-
```
123+
```text
124124
Withdrawing 10.0
125125
Withdrawal failed: insufficient balance
126126
Current balance: 5.0
127127
```
128128

129129
Or, in case an unchecked exception is thrown by the `bankAccount.withdraw(amount)`, the following is printed:
130130

131-
```
131+
```text
132132
Withdrawing -10.0
133133
Withdrawal failed: Cannot withdraw a negative amount
134134
Current balance: 5.0

‎concepts/exceptions/introduction.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -112,23 +112,23 @@ public class ATM {
112112

113113
In this example, when no exception is thrown, the following is printed:
114114

115-
```
115+
```text
116116
Withdrawing 10.0
117117
Withdrawal succeeded
118118
Current balance: 5.0
119119
```
120120

121121
However, should the `bankAccount.withdraw(amount)` statement throw an `InsufficientBalanceException`, the following is printed:
122122

123-
```
123+
```text
124124
Withdrawing 10.0
125125
Withdrawal failed: insufficient balance
126126
Current balance: 5.0
127127
```
128128

129129
Or, in case an unchecked exception is thrown by the `bankAccount.withdraw(amount)`, the following is printed:
130130

131-
```
131+
```text
132132
Withdrawing -10.0
133133
Withdrawal failed: Cannot withdraw a negative amount
134134
Current balance: 5.0

‎concepts/for-loops/introduction.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ for (int i = 1; i <= 4; i++) {
4545

4646
The output would be:
4747

48-
```
48+
```text
4949
square of 1 is 1
5050
square of 2 is 4
5151
square of 3 is 9

‎concepts/foreach-loops/about.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ for(char vowel: vowels) {
2929

3030
which outputs:
3131

32-
```
32+
```text
3333
a
3434
e
3535
i

‎concepts/foreach-loops/introduction.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ for(char vowel: vowels) {
2929

3030
which outputs:
3131

32-
```
32+
```text
3333
a
3434
e
3535
i

‎concepts/interfaces/about.md

-1
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,6 @@ Moreover, the concept of [polymorphism can be implemented through interfaces][in
124124
[so-mocking-interfaces]: https://stackoverflow.com/a/9226437/96167
125125
[comparable]: https://docs.oracle.com/javase/8/docs/api/java/lang/Comparable.html
126126
[wiki-test-double]: https://en.wikipedia.org/wiki/Test_double
127-
[wiki-polymorphism]: https://en.wikipedia.org/wiki/Polymorphism_(computer_science)
128127
[wiki-namespaces]: https://en.wikipedia.org/wiki/Namespace
129128
[wiki-loose-coupling]: https://en.wikipedia.org/wiki/Loose_coupling
130129
[interfaces]: https://docs.oracle.com/javase/tutorial/java/concepts/interface.html

‎config/exercise-readme-insert.md

-20
This file was deleted.

‎config/exercise_readme.go.tmpl

-19
This file was deleted.

‎docs/ABOUT.md

+8-8
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
# About
22

3-
[Java](https://go.java/index.html) is among the most popular available programming languages, thanks to its versatility and compatibility.
3+
[Java](https://go.java/index.html) is among the most popular available programming languages, thanks to its versatility and compatibility.
44
It is widely used for software development, mobile applications and developing larger systems.
55

6-
Java was born in 1995 and is maintained by [Oracle](https://www.oracle.com/index.html).
7-
Despite the fact that it isn't as young as some of the fresh languages out there, Java is still really popular.
8-
It was designed to be fast, secure, reliable, beginner-friendly and highly portable.
9-
This portability perk exists because Java is executed on a cross-platform compatible [Java Virtual Machine - JVM](https://en.wikipedia.org/wiki/Java_virtual_machine).
10-
Android apps are also developed using Java, since the [Android Operating System](https://en.wikipedia.org/wiki/Android_(operating_system)) runs on a Java language environment.
6+
Java was born in 1995 and is maintained by [Oracle](https://www.oracle.com/index.html).
7+
Despite the fact that it isn't as young as some of the fresh languages out there, Java is still really popular.
8+
It was designed to be fast, secure, reliable, beginner-friendly and highly portable.
9+
This portability perk exists because Java is executed on a cross-platform compatible [Java Virtual Machine - JVM](https://en.wikipedia.org/wiki/Java_virtual_machine).
10+
Android apps are also developed using Java, since the [Android Operating System](<https://en.wikipedia.org/wiki/Android_(operating_system)>) runs on a Java language environment.
1111

1212
The Java community is huge!
13-
GitHub for example has over 1.5 million Java projects.
14-
It's also worth mentioning that Java has the second largest community in [StackOverflow](https://stackoverflow.com/questions/tagged/java)!
13+
GitHub for example has over 1.5 million Java projects.
14+
It's also worth mentioning that Java has the second largest community in [StackOverflow](https://stackoverflow.com/questions/tagged/java)!
1515
This is important because the larger a programming language community is, the more support you'd be likely to get.
1616

1717
Java also has a powerful and well-designed set of built-in [APIs - Application Programming Interfaces](https://docs.oracle.com/en/java/javase/11/docs/api/index.html), which can be used for various activities like Database connection, networking, I/O, XML parsing, utilities, and much more.

0 commit comments

Comments
 (0)