You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: CONTRIBUTING.md
+49-97
Original file line number
Diff line number
Diff line change
@@ -1,18 +1,12 @@
1
1
# Contributing
2
2
3
-
Automated Mentoring support for the JavaScript track is a work in progress, and
4
-
it's not uncommon that people discover incorrect analysis, have a better
5
-
approach on detecting certain code paths, report missing edge cases, factual
6
-
errors, logical errors and develop new analysers.
3
+
Automated Mentoring support for the JavaScript track is a work in progress, and it's not uncommon that people discover incorrect analysis, have a better approach on detecting certain code paths, report missing edge cases, factual errors, logical errors and develop new analysers.
7
4
8
-
We welcome contributions of all sorts and sizes, from reporting issues to
9
-
submitting patches, as well as joining the current [💬 discussions][issue-discussion].
5
+
We welcome contributions of all sorts and sizes, from reporting issues to submitting patches, as well as joining the current [💬 discussions][issue-discussion].
10
6
11
7
---
12
8
13
-
This guide covers several common scenarios pertaining to **improving the
14
-
JavaScript analyzer**. There are several other guides about contributing to
15
-
other parts of the Exercism ecosystem.
9
+
This guide covers several common scenarios pertaining to **improving the JavaScript analyzer**. There are several other guides about contributing to other parts of the Exercism ecosystem.
16
10
17
11
-[The JavaScript track][contributing-javascript]
18
12
-[The TypeScript track][contributing-typescript]
@@ -25,56 +19,39 @@ Help us keep Exercism welcoming. Please read and abide by the [Code of Conduct][
25
19
26
20
## Analyzers
27
21
28
-
Before contributing code to any existing analyzer or any new analyzer, please
29
-
have a thorough look at the current analyzers and dive into [the interface][docs-interface]
30
-
and general [analyzer guidelines][docs-guidelines].
22
+
Before contributing code to any existing analyzer or any new analyzer, please have a thorough look at the current analyzers and dive into [the interface][docs-interface] and general [analyzer guidelines][docs-guidelines].
31
23
32
24
### New exercise / analyzer
33
25
34
-
Let's say you want to write a new analyzer, because you've noticed that this
35
-
exercise could benefit from automated mentoring support, or just because you
36
-
find this interesting, the first step is to [check for an open issue][issue-new-exercise].
37
-
If it's there, make sure no one is working on it, and most of all that there is
38
-
not an open Pull Request towards this exercise.
26
+
Let's say you want to write a new analyzer, because you've noticed that this exercise could benefit from automated mentoring support, or just because you find this interesting, the first step is to [check for an open issue][issue-new-exercise].
27
+
If it's there, make sure no one is working on it, and most of all that there is not an open Pull Request towards this exercise.
39
28
40
-
If there is no such issue, you may open one. Take [this issue][sample-resistor-color]
41
-
as a baseline of what should be in it. This serves as a starting point for
42
-
all discussion, as we now must establish a few things before starting to write
43
-
code.
29
+
If there is no such issue, you may open one. Take [this issue][sample-resistor-color] as a baseline of what should be in it.
30
+
This serves as a starting point for all discussion, as we now must establish a few things before starting to write code.
44
31
45
32
#### Project Track Anatomy
46
33
47
-
If the exercise has undergone at least phase 1 of Project Track Anatomy, it is
48
-
likely that there are [mentoring notes][mentor-notes]. These are likely to
49
-
contain what the _maintainers_ of the JavaScript track _or_ the dedicated people
50
-
from the track anatomy project deem to be the set of reasonable solutions.
34
+
If the exercise has undergone at least phase 1 of Project Track Anatomy, it is likely that there are [mentoring notes][mentor-notes].
35
+
These are likely to contain what the _maintainers_ of the JavaScript track _or_ the dedicated people from the track anatomy project deem to be the set of reasonable solutions.
51
36
52
37
#### Abstract Syntax Approach
53
38
54
-
These solutions will be your baseline for `approve`, one of the expected
55
-
outputs. If your analyzer will be based on Abstract Syntax Tree parsing, you can
56
-
run these analyzers through the included ASTParser, or use [AST explorer][ast-explorer]
57
-
and make sure it's set to the correct parser (at moment of writing this is
58
-
`@typescript/eslint-parser`).
39
+
These solutions will be your baseline for `approve`, one of the expected outputs.
40
+
If your analyzer will be based on Abstract Syntax Tree parsing, you can run these analyzers through the included ASTParser, or use [AST explorer][ast-explorer] and make sure it's set to the correct parser (at moment of writing this is `@typescript/eslint-parser`).
59
41
60
42
**Note**: You may write a different style analyzer, that is _not_ using ASTs.
61
43
62
44
#### Discussion 💬 and Samples
63
45
64
-
In your issue, write out how you're going to tackle the initial set of
65
-
solutions, and work on a prototype. If there are no `fixtures` yet, we will
66
-
supply you with a set of fixtures (500, if there are at least 500 submissions)
67
-
so you can run your analyzer using `batch.sh slug` on these fixtures.
46
+
In your issue, write out how you're going to tackle the initial set of solutions, and work on a prototype.
47
+
If there are no `fixtures` yet, we will supply you with a set of fixtures (500, if there are at least 500 submissions) so you can run your analyzer using `batch.sh slug` on these fixtures.
68
48
69
-
It can be very fruitfull to ask current maintainers and previous authors of
70
-
analyzers how to tackle various approaches, especially since there are so many
71
-
ways to write equivalent code in JavaScript.
49
+
It can be very fruitful to ask current maintainers and previous authors of analyzers how to tackle various approaches, especially since there are so many ways to write equivalent code in JavaScript.
72
50
73
51
#### Writing comments
74
52
75
-
Comments are the output of the Analyzer. You don't need to be a great writer in
76
-
order to contribute to the analyzers. How this works inside the repository is
77
-
a guide on its own: read more about [📝 Comments][docs-comments].
53
+
Comments are the output of the Analyzer. You don't need to be a great writer in order to contribute to the analyzers.
54
+
How this works inside the repository is a guide on its own: read more about [📝 Comments][docs-comments].
78
55
79
56
#### Tests
80
57
@@ -85,35 +62,27 @@ Before you submit your PR, make sure that you follow the following docs:
85
62
86
63
### Sync with exercise
87
64
88
-
<!-- Explain that syncs in problem-descriptions need to be synced with the analyzers,
89
-
establish the set of rules how to update, but wait until there is proper
90
-
versioning and how that is given at runtime -->
65
+
<!-- Explain that syncs in problem-descriptions need to be synced with the analyzers, establish the set of rules how to update, but wait until there is proper versioning and how that is given at runtime -->
91
66
92
-
This section will be written once there is consensus on how the input will be
93
-
versioned. Until then, the steps are the same as for writing a new analyzer,
94
-
except that you may skip creating an issue.
67
+
This section will be written once there is consensus on how the input will be versioned.
68
+
Until then, the steps are the same as for writing a new analyzer, except that you may skip creating an issue.
95
69
96
70
### Add new behaviour
97
71
98
72
<!-- Adding new tests is mandatory -->
99
73
100
-
This section will be written once there is consensus on coverage and tests in
101
-
general.
74
+
This section will be written once there is consensus on coverage and tests in general.
102
75
103
76
### Commentary copy
104
77
105
-
This section will be written once there is consensus on how the commentary is
106
-
structured in `website-copy` and what the format for parameters/templates is
107
-
like.
78
+
This section will be written once there is consensus on how the commentary is structured in `website-copy` and what the format for parameters/templates is like.
108
79
109
80
Find all _technical_ details in [the doc about 📝 Comments][docs-comments].
110
81
111
82
## Tools
112
83
113
-
We use various tools to maintain this repository and this analyzer. In order
114
-
to contribute to the _code_ of this track, you'll need NodeJS (LTS or higher)
115
-
installed, with some of the [`bin/*`][file-bin] files having extra dependencies,
116
-
as listed in their file-level commentary.
84
+
We use various tools to maintain this repository and this analyzer.
85
+
In order to contribute to the _code_ of this track, you'll need NodeJS (LTS or higher) installed, with some of the [`bin/*`][file-bin] files having extra dependencies, as listed in their file-level commentary.
117
86
118
87
### `analyze` (.sh, .bat)
119
88
@@ -122,60 +91,45 @@ as listed in their file-level commentary.
122
91
```
123
92
124
93
This runs the analyzer using `two-fer` as exercise and a path to a solution.
125
-
Most scripts, including this one, accept a wide range of flags to change or
126
-
enhance the behaviour, as coded in [`execution_options.ts`][file-execution-options].
94
+
Most scripts, including this one, accept a wide range of flags to change or enhance the behavior, as coded in [`execution_options.ts`][file-execution-options].
127
95
128
96
Run with the `-h` / `--help` flag to get a list of flags and their description.
129
97
130
98
```shell
131
99
./bin/analyze.sh --help
132
100
```
133
101
134
-
You'll most likely want `-dcp` (`--debug`,`--console` and `--pretty`) during
135
-
development, which enables console output (instead of `stdout`/`stderr`) and
136
-
shows `logger.log` as well as `logger.error` and `logger.fatal`. It will also
137
-
format the output JSON with 2 space indentation, both in the output file and
138
-
the console.
102
+
You'll most likely want `-dcp` (`--debug`,`--console` and `--pretty`) during development, which enables console output (instead of `stdout`/`stderr`) and shows `logger.log` as well as `logger.error` and `logger.fatal`.
103
+
It will also format the output JSON with 2 space indentation, both in the output file and the console.
139
104
140
-
If you wish to _preview_ the actual messages, pass in `--noTemplates` to use
141
-
the analyzer `Comment`Factories to generate actual messages. If the comment
142
-
factories are kept in-sync with `website-copy`, it will be the exact same
143
-
output as on the site.
105
+
If you wish to _preview_ the actual messages, pass in `--noTemplates` to use the analyzer `Comment`Factories to generate actual messages.
106
+
If the comment factories are kept in-sync with `website-copy`, it will be the exact same output as on the site.
144
107
145
108
### `batch` (.sh, .bat)
146
109
147
110
```shell
148
111
./bin/batch.sh two-fer -cp
149
112
```
150
113
151
-
Runs all the fixtures in `~/test/fixtures/two-fer` through the analyzer, giving
152
-
a summary at the end with all results. This places an `analysis.json` in the
153
-
source fixture folder.
114
+
Runs all the fixtures in `~/test/fixtures/two-fer` through the analyzer, giving a summary at the end with all results.
115
+
This places an `analysis.json` in the source fixture folder.
154
116
155
-
You'll most likely want `-cp` (`--console` and `--pretty`) during development,
156
-
which enables console output (instead of `stdout`/`stderr`) and formats the
157
-
output JSON with 2 space indentation.
117
+
You'll most likely want `-cp` (`--console` and `--pretty`) during development, which enables console output (instead of `stdout`/`stderr`) and formats the output JSON with 2 space indentation.
158
118
159
-
If you wish to _preview_ the actual messages, pass in `--noTemplates` to use
160
-
the analyzer `Comment`Factories to generate actual messages. If the comment
161
-
factories are kept in-sync with `website-copy`, it will be the exact same
162
-
output as on the site.
119
+
If you wish to _preview_ the actual messages, pass in `--noTemplates` to use the analyzer `Comment`Factories to generate actual messages.
120
+
If the comment factories are kept in-sync with `website-copy`, it will be the exact same output as on the site.
You need the [`exercism` cli][cli] in order for this to work. It takes an
171
-
_exercism solution url_. and downloads it using the `exercism` cli. It then
172
-
runs the analyzer on it.
128
+
You need the [`exercism` cli][cli] in order for this to work.
129
+
It takes an _exercism solution url_. and downloads it using the `exercism` cli.
130
+
It then runs the analyzer on it.
173
131
174
-
You'll most likely want `-dcp --dry` (`--debug`, `--pretty`, `--console` and
175
-
`dry run`) during development, which enables console output (instead of
176
-
`stdout`/`stderr`), shows `logger.log` as well as `logger.error` and
177
-
`logger.fatal`, pretty prints the JSON output and disables writing the output
178
-
to `analysis.json`.
132
+
You'll most likely want `-dcp --dry` (`--debug`, `--pretty`, `--console` and `dry run`) during development, which enables console output (instead of `stdout`/`stderr`), shows `logger.log` as well as `logger.error` and `logger.fatal`, pretty prints the JSON output and disables writing the output to `analysis.json`.
179
133
180
134
You can pass the following type of URLs:
181
135
@@ -184,25 +138,23 @@ You can pass the following type of URLs:
184
138
- Your solutions: `/my/solutions/<id>`
185
139
- Private solutions: `/solutions/<id>`
186
140
187
-
If you wish to _preview_ the actual messages, pass in `--noTemplates` to use
188
-
the analyzer `Comment`Factories to generate actual messages. If the comment
189
-
factories are kept in-sync with `website-copy`, it will be the exact same
190
-
output as on the site.
141
+
If you wish to _preview_ the actual messages, pass in `--noTemplates` to use the analyzer `Comment`Factories to generate actual messages.
142
+
If the comment factories are kept in-sync with `website-copy`, it will be the exact same output as on the site.
0 commit comments