-
Notifications
You must be signed in to change notification settings - Fork 6
Contributing
While Brat is often a fast moving target, there are still plenty of ways to contribute to the project.
This page lists ways of getting involved. See also How to Contribute and Getting Help.
These are ways of helping out with Brat that require very little effort at all, but are very helpful.
People can't use Brat if they can't even install it! Try installing Brat on your machine and file an issue if you run into any problems. You don't have to know how to fix it, just letting someone know there is a problem is great.
There are a bunch of examples written in Brat here and on Rosetta Code. Try them out and report any wrong output or misbehavior.
There are a bunch of tests included with the Brat code. To run them, do something like:
./brat test/test.brat
(If it is not clear how to run the tests, ask for clarification!)
If all the tests pass, then great! Passing tests will have some output like this:
Overall results: 299 tests, 772 assertions, 0 failures.
All systems are go!
If there is a failing test, it might look like this:
Test failure(s):
1. 'set_delete': expected 0, but was 1
8 tests, 24 assertions, 1 failures.
Please report any failing tests using an issue.
This can uncover all sorts of issues in itself: parsing problems, broken methods, missing functionality...if you run across any weirdness, try asking about it in an issue.
Here are some ways of contributing to the project which do not require real deep understanding of how Brat is implemented, but are still awesome.
Writing new examples is a great way to learn Brat and expand the amount of code written in Brat.
No ideas for new examples? Try completing a task on Rosetta Code!
If you write a new example, please add it to your fork and then send a pull request.
Brat has a bunch of tests in the test/ directory. They are arranged into pretty broad categories and each file is very similar:
include :assert
add_results setup name: "some tests" {
test "specific thing" {
assert_equal expected_value { test_code }
}
}
Pick a test file and browse through it to get a feel for how they are written.
The file begins with including the assert library. This provides the setup, test, and assert methods. (For now, ignore add_results.)
setup groups a bunch of tests together. Then name should be something descriptive.
Inside setup there are a bunch of tests. Each test should be checking something more specific, like a particular method or even more specific: a particular use of a particular method.
Inside each test are one or more assertions. There are several methods used for these, such as assert, assert_equal, assert_false, and so on. (A good project would be to document these!!) Each assertion is tested in order. If any of them fail, the entire test is marked as failing.
Uses of tests
Tests can be used for many purposes, including demonstrating a problem (a test fails in a situation where it is expected to succeed), explaining a new feature (provide a test showing desired functionality), documenting existing behavior, and exploring weird edge cases.
Any kind of test you would like to add would be welcome! Fork away!
The Brat core often expands more rapidly than it is documented. Sometimes this is adding new methods, other times it is adding functionality to existing methods.
One way to find missing documentation is to check the methods available on an object and compare it to the documentation on the website.
For example, you might look at methods on a string:
brat:1> "".methods.sort
#=> [*, +, <, <<, <=, <=>, ==, >, >=, all?, alpha?, alphanum?, any?, blank?, chomp, chomp!, dice, downcase, downcase!, each, find, get, include?, length, match, max, min, new, numeric?, parent, reject, reverse, reverse!, reverse_each, select, set, split, string?, strip, strip!, sub, sub!, sub_first, sub_first!, to_byte, to_f, to_i, to_s, upcase!]
Then compare to the methods listed here. Some are probably missing!
There are two ways of adding documentation: for the website and add the documentation there, or else adding comments to the code explaining how a method works. Either way, make a fork, add the documentation, and send a pull request.
These suggestions might require a bit more elbow grease.
If you can fix broken examples, then that's awesome! Fork the code, fix it, and send a pull request.
If you find a failing test, try to isolate the issue (already a big accomplishment!) and then try to fix it!
The following suggestions may take a considerable amount of work.
Brat is currently very limited in the standard library area.
Libraries can be written in either Brat or Lua. Writing a library in Lua requires some understanding of how the core of Brat is implemented and how to interact with it.
(More documentation pending.)
When adding a standard library or extending an existing one, please add tests, too!
Much of Brat's functionality lies in core/core.lua, where all the main objects (array, string, etc.) are implemented. Adding a method to one of these objects requires a thorough understanding of the core implementation, or at least copying of a similar method.
When changing anything in the core, please add tests for the new/different functionality! These not only proves that the changes work, but the tests can also show what the changes are supposed to do.
Wow, these are serious work.
These hairy mess resides in parser/brat.treetop and parser/parser-extension.rb. Making it better makes everything better.
There are some (many?) edge cases for parsing that may not behave as expected. First ask (with an example!) via an issue to see what the expected behavior is. Then dive in! Don't forget your scuba gear.
There are almost certainly inefficiencies in core/core.lua. Feel free to find and fix them!