wren/doc/site/contributing.markdown

^title Contributing

Wren is under active development and there's lots to do. We'd be delighted to have you help!

Getting acquainted

Pull requests and bug reports are always welcome. But, if you'd like to dip your toes in the water before diving in, please join the mailing list and say, "Hi". There's no strangers to Wren, just friends we haven't met yet.

The source

Wren uses the OSI-approved MIT license. I'm not sure exactly what that means, but I went with the most permissive license I could find.

The source is developed on GitHub. My 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

Eventually, the issue tracker will be populated with a more complete set of changes and features I have in mind. Until then, one easy way to find things that need doing is to look for TODO comments in the code.

Also, writing code in Wren and seeing what problems you run into is incredibly helpful. Embedding Wren in an application will also exercise lots of corners of the system and highlight problems and missing features.

Of course, new ideas are also 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:

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

Now you can build the docs:

:::sh
$ make docs

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

:::sh
$ 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:

:::sh
$ 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:

    :::sh
    $ 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.

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. Thank you!