Contributing

All are welcome. All are welcome.

Please follow this guide for reporting issues and submitting pull requests. The majority of this guide was heavily “borrowed” from Marionette’s contribution guidelines.

Lazo has a few guidelines to facilitate your contribution and streamline the process of getting the changes merged in and released.

Running the tests

To begin ensure that you have installed the project dev dependencies via:

$ npm install

Lazo leverages intern for running client and server tests:

$ grunt test

Documentation Fixes

If you notice any problems with any documentation, please fix it and we'll get it merged as soon as we can. For small things like typos and grammar (which we know I'm terrible with), just click the "Edit this file" button and send in the pull request for the fix. For larger changes and big swaths of documentation changes, a regular pull request as outlined below is more appropriate.

Pull Requests

See Github's documentation for pull requests.

Pull requests are by far the best way to contribute to Lazo. Any time you can send us a pull request with the changes that you want, we will have an easier time seeing what you are trying to do. But a pull request in itself is not usually sufficient. There needs to be some context and purpose with it, and it should be done against a specific branch.

Code changes should be made off of the "development" branch in your fork and pull requests made against walmartlabs/lazojs#development.

Try and stick to Lazo's existing coding conventions (we need to establish these).

General Submission Guidelines

These guidelines are generally applicable whether or not you are submitting a bug or a pull request. Please try to include as much of this information as possible with any submission.

Version Numbers

In order to best help out with bugs, we need to know the following information in your bug submission:

• Lazo version #
• Operating System / version #
• Browser and version #

Including this information in a submission will help us to test the problem and ensure that the bug is both reproduced and corrected on the platforms / versions that you are having issues with.

Provide A Meaningful Description

It doesn't matter how beautiful and "obvious" your fix is. We have 10,000,000,000 things floating around the project at any given moment and we will not immediately understand why you are making changes.

Given that, it is very important to provide a meaningful description with your pull requests that alter any code. A good format for these descriptions will include three things:

1. Why: The problem you are facing (in as much detail as is necessary to describe the problem to someone who doesn't know anything about the system you're building)

2. What: A summary of the proposed solution

3. How: A description of how this solution solves the problem, in more detail than item #2

4. Any additional discussion on possible problems this might introduce, questions that you have related to the changes, etc.

Without at least the first 2 items in this list, we won't have any clue why you're changing the code. The first thing we'll ask, then, is that you add that information.

Please refrain from giving code examples in altJS languages like CoffeeScript, etc. Lazo is written in plain-old JavaScript and is generally easier all members in the community to read.

If your pull request contains commits or other changes that are not related to the pull request, we will ask you to re-do your pull request.

Submit Specs With Your Pull Request

Whenever possible, submit the specs (unit tests) that correspond to your pull request.

I would rather see a pull request that is nothing but a failing spec, than see a large change made to the real code with no test to support the change.

In fact...

Submit A Failing Spec If You Don't Know How To Fix The Problem

If you are stuck in a scenario that fails in your app, but you don't know how to fix it, submit a failing spec to show the failing scenario. Follow the guidelines for a pull request submission, but don't worry about fixing the problem. A failing spec to show that a problem exists is a very very very helpful pull request for us.

We'll even accept a failing test pasted in to the ticket description instead of a pull request. That would at least get us started on creating the failing test in the code.