wren

a classy little scripting language

Contributing

Like the bird, Wren’s ecosystem is small but full of life. Almost everything is under active development and there’s lots to do. We’d be delighted to have you help.

The first thing to do is to join the official mailing list and say, “Hi”. There are no strangers to Wren, just friends we haven’t met yet.

Growing the ecosystem #

The simplest and often most helpful way to join the Wren party is to be a Wren user. Create an application that embeds Wren. Write a library or a handy utility in Wren. Add syntax highlighting support for Wren to your favorite text editor. Share that stuff and it will help the next Wren user to come along.

If you do any of the above, let us know by adding it to the wiki. We like to keep track of:

Contributing to Wren #

You’re also more than welcome to contribute to Wren itself, both the core VM and the command-line interpreter. The source is developed on GitHub. Our hope is that the codebase, tests, and documentation are easy to understand and contribute to. If they aren’t, that’s a bug.

Finding something to hack on #

Between the issue tracker and searching for TODO comments in the code, it’s pretty easy to find something that needs doing, though we don’t always do a good job of writing everything down.

If nothing there suits your fancy, new ideas are welcome as well! If you have an idea for a significant change or addition, please file a proposal to discuss it before writing lots of code. Wren tries very very hard to be minimal which means often having to say “no” to language additions, even really cool ones.

Hacking on docs #

The documentation is one of the easiest—and most important!—parts of Wren to contribute to. The source for the site is written in Markdown (and a little SASS) and lives under doc/site. A simple Python script, util/generate_docs.py, converts that to HTML and CSS.

The site uses Pygments for syntax highlighting, with a custom lexer plug-in for Wren. To install that, run:

$ cd util/pygments-lexer 
$ sudo python setup.py develop 
$ cd ../.. # Back to the root Wren directory.

Now you can build the docs:

$ make docs

This generates the site in build/docs/. You can run any simple static web server from there. Python includes one:

$ cd build/docs 
$ python -m SimpleHTTPServer

Running make docs is a drag every time you change a line of Markdown or SASS, so there is also a file watching version that will automatically regenerate the docs when you edit a file:

$ make watchdocs

Hacking on the VM #

The basic process is simple:

  1. Make sure you can build and run the tests locally. It’s good to ensure you’re starting from a happy place before you poke at the code. Running the tests is as simple as:

    $ make test
    

    If there are no failures, you’re good to go.

  2. Fork the repo so you can change it locally. Please make your changes in separate feature branches to make things a little easier on me.

  3. Change the code. Please follow the style of the surrounding code. That basically means camelCase names, { on the next line, keep within 80 columns, and two spaces of indentation. If you see places where the existing code is inconsistent, let me know.

  4. Write some tests for your new functionality. They live under test/. Take a look at some existing tests to get an idea of how to define expectations.

  5. Make sure the tests all pass, both the old ones and your new ones.

  6. Add your name and email to the AUTHORS file if you haven’t already.

  7. Send a pull request. Pat yourself on the back for contributing to a fun open source project! I’ll take it from here and hopefully we’ll get it landed smoothly.

Getting help #

If at any point you have questions, feel free to file an issue or ask on the mailing list. You can also email me directly (robert at stuffwithstuff.com) if you want something less public.