Skip to content

Latest commit

 

History

History
234 lines (165 loc) · 7.54 KB

CONTRIBUTING.md

File metadata and controls

234 lines (165 loc) · 7.54 KB

Contributing to RacketScript

First off, thanks for taking the time to contribute! We need volunteers to help this project grow and become successful.

The following is a set of guidelines for contributing to RacketScript. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Code of Conduct

Reporting Bugs, Features and Enhancements

Hacking

Submitting Changes

Style Guide

Additional Resources

Tips and Tricks

Code of Conduct

This project and everyone participating in it is governed by the RacketScript Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Reporting Bugs, Features and Enhancements

We use Github Issues for tracking bugs, features, enhancements and other discussions.

  • Ensure the issue was not already reported by searching on GitHub under Issues.
  • If you're unable to find an open issue addressing the same, open a new one
  • Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.

Hacking

Setup Development Environment

To start hacking on the RacketScript codebase you will need some extra tools and packages for running tests, lints and coverage.

make setup-extra  # From RacketScript codebase root

The compiler is written in Typed Racket. To avoid long startup times, it is advised to pre-compile Racket sources to bytecode.

make build  # From RacketScript codebase root

Get familiar with the various command line options provided by the RacketScript CLI racks and Node.

Testing

We have unit tests for testing compiler code, and integration tests which tests both compiler and runtime.

Unit Tests

Unit tests cover the compiler codepath. Unit tests can be found in the original Racket source files in the test submodule.

# Run unit tests
make unit-test

Integration Tests

Integration tests are used to do end-to-end testing of RacketScript. Therefore, any compiler or runtime changes must pass the integration test suite.

# Run integration tests
make integration-test
# Run all tests
make test

Integration tests can be found in the tests/ subdirectory. The tests are Racket code fragments which are compiled with both Racket and RacketScript. The resulting Racket and JavaScript programs are then executed and a test fails if the two runs do not produce identical outputs.

The tests are organized in various folders. Running the complete integration test suite can take several minutes. fixtures.rkt can run individual or a specific set of tests.

# To run specific test
$ ./fixture.rkt basic/let.rkt

# To run all tests in a folder
$ ./fixture.rkt basic/

# To run run all tests which match a glob pattern
$ ./fixture.rkt basic/procedure-*.rkt

# Its a good idea to get familiar with `fixture.rkt` as well
$ ./fixture.rkt -h

Coverage

To produce a coverage report of the test suite:

# Consider coverage of all tests
$ make coverage

# Just consider unit-test coverage
$ make coverage-unit-test

Currently only the compiler codebase is covered in the report. The runtime, including kernel.rkt, is not considered in this report even though it actually is covered by our test suite.

Submitting Patches

Make sure that there is an open ticket for the issue you want to work on, to avoid duplicate effort and to keep the maintainers informed.

For small/trivial changes, you can submit a pull request directly. In this case, make sure that the PR contains all the information that you would otherwise provide in the issue ticket.

  • Open a new GitHub pull request against master branch.
  • Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
  • Make sure the test suite passes and your changes are covered. Note that for runtime changes it is not possible to get coverage report (see Coverage). We use GH Actions for continuous integration.
  • Adhere to the style guide (you can use linters for JavaScript).

We like small patches. They are easier to reason about and review.

  • Use your best judgment to split the pull request into a logical set of patches that tackles one problem at a time.
  • Avoid making changes that are unnecessary for the current task at hand. They should ideally be a separate issue. If necessary, follow the previous point.
  • Make sure your patches have a good commit message, title, and description, and reference the relevant Gitub issue number (see additional resources on Git).

For larger changes, it is good practice to maintain open communication in order to receive continuous feedback. This encourages participation from the entire community and saves effort by avoiding major design changes at later stages of the task.

Style Guide

Tips and Tricks

Using multiple Racket versions

If you develop with multiple versions of Racket and don't have the current Racket bin directory in your path, you may find the following racks shim useful (place it in your bin path):

#!/bin/bash

"$(racket -e "(require setup/dirs) (display (find-user-console-bin-dir))")/racks" "$@"

Changing root NPM directory

If you do not wish to pollute your root NPM directory, you can set a custom global location by changing your npmrc (eg. echo "prefix = $HOME/.npm-packages" >> ~/.npmrc. Then add /prefix/path/above/bin to your PATH.

Get familiar with the tools

Get familiar with the tools used for development such as racks, nodejs, babel, make, fixture.rkt etc. See the various targets available in Makefile for usage examples.

Over the life of RacketScript, we've added various command line flags to assist development workflow and to save time and misery. Don't hesitate to file an issue with new ideas to improve this area!

Additional Resources

Git, patches and pull requests

Miscellaneous

Attribution

These guidelines are adapted from: