Contributing

Here are the principles we follow to ensure the quality of our products.

Linters

Testing

The documentation describes the tests. A tool extracts the examples given in the documentation and ensures that the stated functionality exists in the project.

The recommended kind of testing is acceptance tests. The tests are unaware of the implementation of the feature they are testing. They check that given the input the output is as expected. For example, when the compiler parses a file, it generates X amount of files, and those files have no syntactical errors.

Parser

The following code should compile without parsing errors:

something { component value }

The following should fail at parsing with the parsing error of unexpected EOF:

something { component value 

We should be able to explain these texts in a more human friendly way, but still automate them to check their veracity.

Strace black box testing

Version control

Always format. This way the versioned files have a consistent format and don't have updates for formatting issues.

If it's easier to generate, generate the code and version control the script that generates it. If it's easier to type the code, type the code and version control it.

For example, it's easier to write xtext grammars by hand than generating them and thus are version controlled. it's easier to write a generator for blockly webpages than maintaining the html xml and js files, and thus the generator is version controlled.

It's easier to maintain a build script like build.gradle or package.json than all the dependencies, and thus the build scripts are version controlled.

Writing the build script is easier than generating it, so we version control the build script instead of generating it.

What about git hook scripts? Generating them would take longer than writing them thus we version control them and install them with the build tool.

Folder structure, if files have same extension, group them in folders. If files need to be in the root folder, put them in the root folder. Examples include package.json, .gitignore, README.md and SUMMARY.md. Otherwise group them in folders. Examples include hooks and guides.

The post-commit hook generates SUMMARY.md if the commit is valid.

Npm has packages for gitbook-summary, pre-commit and post-commit.

Ideal folder structure:

• package.json
• README.md
• 0 Beginner guide
  • Subfolders
  • Subfolders
• 1 User guide
  • Subfolders
  • Subfolders
• 2 Developer guide
  • Subfolders
  • Subfolders