From 2e27c23f03cd65b0901f9d7d51a3d98fcf02af2b Mon Sep 17 00:00:00 2001 From: Benjamin Pannell Date: Sun, 12 Jul 2015 21:11:21 +0200 Subject: [PATCH] Added a contribution information file Should help new developers start working with Iridium --- CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b39300e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to Iridium +This guide should get you started with most of the information you'll need to begin contributing to Iridium's development. +We've tried to keep the development process as straightforward as possible through a combination of CI tools, unit tests and gulp. + +## Setting up your system +You'll need to have an up to date version of Node.js installed (anything after *0.10.x* should work) - you can grab a copy from +[nodejs.org/download](https://nodejs.org/download/). Once you've got that installed you'll have `npm` available - the Node.js +Package Manager. + +Next thing to do is install Gulp on your system, just run `npm install -g gulp` and wait for that to finish. That will add the +`gulp` command line utility which you will use to manage the Iridium development workflow. + +## Project layout + + - **benchmarks** holds any benchmark files, they're not currently used for unit testing or anything like that, but you can use + them as a rough map between the different comparison libraries. If you decide to write any benchmarks, please stick to using + TypeScript as it will help with refactoring should the API change. + - **build** holds JavaScript files consumed by Gulp for the various gulp tasks available to you. Files within this folder are + automatically run whenever you execute `gulp` within the project directory. + - **dist** holds the compiled JavaScript and JSMap files, its structure mirrors that of the project's root directory. Generally + you won't have any need to fiddle in here unless you're debugging a code generation issue. + - **example** holds a couple of example files which show how you can go about doing certain things within Iridium. If you've got + a good idea for an example then this is where you should put it. Generally you'll write these in TypeScript, but if you want + to create an example of how to do things in JavaScript or any other JS targetting language then go right ahead. + - **lib** *This is where the magic happens!* TypeScript files which make up the heart of Iridium. + - **test** Probably the second most important folder, it holds all of the unit tests used to ensure that Iridium is working the + way it was intended. + - **typings** holds the TypeScript definition files we use to interface with some of the JavaScript dependencies. These are + primarily pulled in by [tsd](http://definitelytyped.org/tsd/) from the [DefinitelyTyped](http://definitelytyped.org/) + project. + +## Developing on Iridium +Iridium's development workflow is almost entirely automated through a combination of Gulp and NPM hooks. The most common command +you'll be using is `gulp watch` which will watch the **lib** and **test** folders for changes, compile the TypeScript files and +run the unit tests. You'll generally leave this running while you make changes to be notified almost immediately when things +break. + +## Pull Request Requirements +1. **KISS** - Keep your pull requests as small and to the point as possible, it makes reviewing the code easier and generally reduces + the likelihood of merge conflicts - which will slow down the process of reviewing your PR. +2. **TEST** - Make sure that whatever new functionality you add has ample unit tests to go along with it, we use code coverage as an + automated requirement for PR merges and it helps make sure we don't break things later down the road. If you aren't sure about + how to write unit tests, please feel free to ask for help in your PR. +3. **KEEP** - Make sure that whatever changes you make, they keep to the existing Iridium API. Iridium adopts the + [Semantic Versioning](http://semver.org) specification, so breaking API changes will result in a major version bump, which + will further slow the process of accepting your pull request (bumping the major version requires work from developers who make + use of our library in most cases - which isn't ideal). The easiest way to ensure that your changes maintain the Iridium API + is just by keeping all the existing unit tests as they are.