Skip to content

Latest commit

 

History

History
161 lines (105 loc) · 8.84 KB

CONTRIBUTING.md

File metadata and controls

161 lines (105 loc) · 8.84 KB
Raw

Contributing

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.

We welcome contributions of all sorts and sizes, from reporting issues to submitting patches, as well as joining the current 💬 discussions.

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.

Code of Conduct

Help us keep Exercism welcoming. Please read and abide by the Code of Conduct.

Analyzers

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 and general analyzer guidelines.

New exercise / analyzer

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. 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.

If there is no such issue, you may open one. Take this issue as a baseline of what should be in it. This serves as a starting point for all discussion, as we now must establish a few things before starting to write code.

Project Track Anatomy

If the exercise has undergone at least phase 1 of Project Track Anatomy, it is likely that there are mentoring notes. 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.

Abstract Syntax Approach

These solutions will be your baseline for approve, one of the expected outputs. If your analyzer will be based on Abstract Syntax Tree parsing, you can run these analyzers through the included ASTParser, or use AST explorer and make sure it's set to the correct parser (at moment of writing this is @typescript/eslint-parser).

Note: You may write a different style analyzer, that is not using ASTs.

Discussion 💬 and Samples

In your issue, write out how you're going to tackle the initial set of solutions, and work on a prototype. 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.

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.

Writing comments

Comments are the output of the Analyzer. You don't need to be a great writer in order to contribute to the analyzers. How this works inside the repository is a guide on its own: read more about 📝 Comments.

Tests

Before you submit your PR, make sure that you follow the following docs:

Sync with exercise

This section will be written once there is consensus on how the input will be versioned. Until then, the steps are the same as for writing a new analyzer, except that you may skip creating an issue.

Add new behaviour

This section will be written once there is consensus on coverage and tests in general.

Commentary copy

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.

Find all technical details in the doc about 📝 Comments.

Tools

We use various tools to maintain this repository and this analyzer. In order to contribute to the code of this track, you'll need NodeJS (LTS or higher) installed, with some of the bin/* files having extra dependencies, as listed in their file-level commentary.

analyze (.sh, .bat)

./bin/analyze.sh two-fer ~/folder/to/solution -dcp

This runs the analyzer using two-fer as exercise and a path to a solution. Most scripts, including this one, accept a wide range of flags to change or enhance the behavior, as coded in execution_options.ts.

Run with the -h / --help flag to get a list of flags and their description.

./bin/analyze.sh --help

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. It will also format the output JSON with 2 space indentation, both in the output file and the console.

If you wish to preview the actual messages, pass in --noTemplates to use the analyzer CommentFactories to generate actual messages. If the comment factories are kept in-sync with website-copy, it will be the exact same output as on the site.

batch (.sh, .bat)

./bin/batch.sh two-fer -cp

Runs all the fixtures in ~/test/fixtures/two-fer through the analyzer, giving a summary at the end with all results. This places an analysis.json in the source fixture folder.

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.

If you wish to preview the actual messages, pass in --noTemplates to use the analyzer CommentFactories to generate actual messages. If the comment factories are kept in-sync with website-copy, it will be the exact same output as on the site.

remote (.sh, .bat)

./bin/remote.sh https://exercism.io/tracks/javascript/exercises/two-fer/solutions/df3bb5d7131c44ea9c62206cc8d6c225 -dcp --dry

You need the exercism cli in order for this to work. It takes an exercism solution url. and downloads it using the exercism cli. It then runs the analyzer on it.

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.

You can pass the following type of URLs:

  • Published solutions: /tracks/javascript/exercises/<slug>/<id>
  • Mentor solutions: /mentor/solutions/<id>
  • Your solutions: /my/solutions/<id>
  • Private solutions: /solutions/<id>

If you wish to preview the actual messages, pass in --noTemplates to use the analyzer CommentFactories to generate actual messages. If the comment factories are kept in-sync with website-copy, it will be the exact same output as on the site.