Skip to content

Latest commit

 

History

History
66 lines (39 loc) · 3.66 KB

CONTRIBUTING.md

File metadata and controls

66 lines (39 loc) · 3.66 KB
Raw

Contribution guidelines

First of all, thanks for contributing to emuto! All contribution is welcome.

Setup

Make sure you have node and yarn installed.

Fork the repo and clone your fork. Run yarn checks in the repo. It'll set up dependencies and makes sure everything works fine in your environment. If you are having problems after yarn checks, please create an issue!

Workflow

How you develop emuto is really a matter of taste, but here are a few tips:

  • I found TDD and taking baby steps really useful
  • When implementing a new feature or fixing a bug I usually start by adding an integration test in interpreter.test.js. Then I implement changes in parsers and then in generators. (Or builtin functions). I use the pattern feature in jest to focus on the tests that I'm currently working on.

To get your contribution merged you'll need to take these steps:

  1. Take or create an Issue
  2. Create a Pull Request that fixes and references the issue either in its commit messages or it's description
  3. Get code review and fix any comments that come up

You can save time if you run yarn test and yarn checks before each push, as they can detect many issues that would otherwise only be detected during code review or CI.

General best practices

  • Try to make your commits small and atomic. It's best to separate features and bug fixes from refactors. It's also best to make sure that tests are always passing after your commit.
  • Try to avoid increasing the binary size unnecessarily, as emuto is meant to be runnable in a browser as well as in node
  • Don't introduce breaking changes.

Commit message guidelines

We are using Angular Commit Message Guidelines please always make sure that your commit messages are correct. Your commit message will be used in the release script.

The easiest way to compose correct commit messages is to use commitizen.

Project structure

emuto consist mainly of parsers and code generators.

Parsers

Parsers are responsible for parsing distinct syntactical features of emuto. Every parser has to produce an AST node which can be of the flow type NodeType. Multiple parsers can be combined together to create more complex parsers.

Parsers reside in src/parsers/. Tests for parsers reside in src/parsers/__tests__.

Tests for parsers have to test syntactical features and edge cases, and nothing else.

Generators

Generators are responsible for converting AST nodes into JavaScript code. Every generator has to take an AST node and convert it to JavaScript. Generators can recursively call src/generators/generator to compile sub-trees.

Parsers reside in src/generators/. Tests for parsers reside in src/generators/__tests__. There is a main generator in src/generators/generator which has to be able to compile any AST node, and it combines all other generators to fulfill that requirement. Therefore if you implement a new generator you have to also include it in src/generators/generator.

Tests for generators have to test cases that affect the generated code, and nothing else.

End-to-end test

If you are implementing a new feature that either changes a parser or a generator, you also have to change an end-to-end test or implement a new one. End-to-end tests reside in src/__tests__/interpreter.test.js. The output of your code example will be automatically tested and snapshots will be generated for the corresponding AST and target code. This enables us to detect unintended changes in later Pull Requests.