Contributing new features
This guide shows how you can propose the implementation of new features for Folktale.
- Before you start…
- Setting things up for the first time
- File headers
- Making your changes
- Adding tests
- Adding documentation
- Crediting yourself
- Before proposing your changes…
- Proposing your changes
Before you start…
Folktale has a roadmap which summarises the vision for the future of the library. Points in this roadmap are broken down into features, and detailed on the issue tracker as a feature proposal.
Important If a feature is not in the roadmap, please submit a feature request explaining why it should be added before you start to work on it.
When features are specified, they get an issue in the GitHub issue tracker with a
k:Feature label. An issue marked as
in progress means that someone’s already working on it. If it’s not, please comment on the issue so you can be assigned to it.
Features on the roadmap
If a feature is in the roadmap, but doesn’t have a specification on GitHub yet you can create an issue to discuss how that feature could be implemented.
Setting things up for the first time
Once you’re ready to start working on implementing the feature, you’ll want to get your own copy of Folktale. After forking, you can clone your repository to start working on it. GitHub has a visual guide for this workflow, which you may want to read if you’re not familiar with it.
Make sure you’ve got the development tools Folktale uses installed by running
npm install at the Folktale directory:
$ npm install
$is not part of the command, but rather indicates that you should run the command with your regular user account, instead of an administrator account.
Making your changes
To compile the files, run:
$ ./node_modules/.bin/furipota run compile
At the root of the project. This will generate the compiled files at the root as well, and you can require them right from the Node.js REPL, like so:
>> var folktale = require('.'); >> folktale.core.lambda.identity('hello'); 'hello'
Every feature patch should include automated tests. These tests should cover the possible usages of the functionality in question, and ideally be described as mathematical properties, so they can be ran over a broad range of inputs. Refer to the test writing guide for details :)
Every feature patch should include documentation for the public-facing functions, objects, and modules that it introduces.
Documentation consists of two parts:
- A markdown prose, with examples, in the
Meta-data is attached to entities using a YAML doc comment. It’s required to define the
stability of all entities. For functions, the
type is required, and when non-trivial, a
complexity annotation describing the algorithimic complexity in Big O notation.
The documentation guide goes into more details about meta-data annotations and markdown documentation.
If it’s your first time contributing to the project, please take your time to add your name to the
CONTRIBUTORS.md file at the root of the project as well. Just add a new line with the following format:
- Your Preferred Name (Your URL) <email@address>
- Quil (http://robotlolita.me/) <queen at robotlolita.me>
All fields besides the name are optional. As for the name, just pick any that you’re comfortable with being public (it can be your GitHub username, for example). It doesn’t have to be your real name.
Before proposing your changes…
Make sure all existing tests pass by running:
$ ./node_modules/.bin/furipota run test
Make sure your code conforms to the coding style used by the project by running:
$ ./node_modules/.bin/furipota run lint
Proposing your changes
Once you’re done making your changes, open a pull request to propose your changes. You may also open a pull request for work in progress if you want to discuss the changes, or want guidance on some aspect of the code.
A Pull Request is pretty much a way of opening a discussion on some code. Don’t be afraid of showing something that you think is unfinished or could be better, we’re here to help (and we don’t bite!).
Once we’re both happy with the changes, it gets merged in the main branch of Folktale, and scheduled for the next release.
That’s it! Thanks so much for your help :)