Skip to content

Latest commit

 

History

History
144 lines (95 loc) · 7.17 KB

CONTRIBUTING.md

File metadata and controls

144 lines (95 loc) · 7.17 KB
Raw

Contributing

Many thanks for using Ractive and contributing to its development. The following is a quick set of guidelines designed to maximise your contribution's effectiveness.

Reporting security vulnerabilities

If you think you've found a security vulnerability, please email ractive-js-security@googlegroups.com with details regarding the issue. Someone from the team will respond to assist you.

Raising issues

Issues can be anything. It can be questions, feature requests, enhancements, optimizations and more.

For bug-related issues, please make sure you are using the latest stable build. The latest stable build can be found at https://unpkg.com/ractive. If the bug persists, it may have been fixed in the latest "edge" build. Edge builds can be found at https://unpkg.com/ractive@edge and are updated on every change to the dev branch.

When filing an issue, please follow the issue template provided. The best issues contain a reproducible demonstration of the bug in the form of a demo. This jsfiddle has a basic setup to get started with. Even better, you could create a failing test case using this jsfiddle as a base.

Development

Required software

  • Git
  • An editor with the following integrations:
  • A real shell
    • Ubuntu: Use the built-in terminal.
    • macOS: Use the built-in terminal.
    • Windows: Git Bash (from Git for Windows) or Windows Command Prompt.

When using Windows Command Prompt, the build:* and release:* npm scripts will not be available as they use bash scripts. In the case of build:* bash scripts, however, the scripts simply call module binaries which can be run manually.

Hacking Ractive

Fork the repository to your Github account by clicking the "Fork" button on the Ractive.js repository page. Then do the following:

# Clone your fork of the repo
git clone https://github.com/YOUR_USERNAME/ractive

# Move into the repo directory
cd ractive

# Install the dependencies
npm install

# Run a server for development
npm run dev:browser

# Run a build locally (linting, bundling, testing)
# Linux/Unix
npm run build:local

# Windows
npm run bundle:release

# The .build folder contains the various Ractive distributions

http://localhost:4567 serves the sandbox page which you can use to hack Ractive. The files can be found in the sandbox directory. http://localhost:4567/qunit serves the unit tests which can be found in tests/browser. Modifications to src, tests/browser, sandbox, and polyfills will automatically rebuild the sources served in this mode.

http://localhost:4567/playground hosts an instance of the ractive.js.org playground that will automatically use the locally build version of Ractive. Depending on what you're doing, this can be more convenient than the sandbox.

Style guide

Code should be clean, readable, and commented where necessary.

Most of the coding standards are handled by ESLint and EditorConfig configurations. When using an editor with ESLint and EditorConfig support, the editor will guide you in writing code. In addition, builds will fail if the coding standards are not met.

If you want to fix any code or formatting issues that are automatically fixable, you can npm run lint:fix:all.

Testing

Tests use QUnit. Check out their API documentation to learn more on how to write QUnit tests.

Tests can be found in the tests directory, separated by platform and functionality. The helpers directory contains files common to all tests, but do not contain tests. To write tests, simply look for an existing file named after the functionality you're testing and write your tests there.

A sample test file will look like this:

// A short description of the test and the associated Github issue number.
test( 'The thing that is supposed to happen does in fact happen (#42)', t => {

    // Your test case here. Always put messages on the assertions.
    const ractive = new Ractive({});
    t.ok(ractive, 'should create an instance');
});

Guidelines

  • Test as few things as possible per test.
  • Test against the public API, not against implementation details.
  • Tests should be isolated, portable, and readable.
  • Tests should clean up after themselves.
  • Tests and assertions should be described properly.

Utility functions

Utility functions can be found in tests/helpers/test-config module to aid in writing tests. It has the following helper functions and properties:

  • initModule (Function) - QUnit.module with additional setup.
  • onWarn (Function) - Accepts a function and assigns it as console.onwarn.
  • onLog (Function) - Accepts a function and assigns it as console.log.
  • hasUsableConsole (boolean) - A boolean indicating the presence of a console.
  • beforeEach (Function) - Qunit's beforeEach that integrates with initModule.
  • afterEach (Function) - Qunit's afterEach that integrates with initModule.

Sometimes it's necessary to use beforeEach and afterEach in order to avoid repeating lots of code. However, you should try to avoid them – it prevents tests from being portable and makes them hard to read when they're on their own. A test suite is one of the rare occasions when you shouldn't worry too much about DRY.

Triggering DOM events

You can use simulant to simulate DOM interaction in tests (i.e. clicks, mouseovers, etc.). It is exposed to the unit tests as the simulant global module.

import { fire } from 'simulant';

test( 'Click events work', t => {
  t.expect( 1 );

  const ractive = new Ractive({
    el: fixture,
    template: `<button on-click='test(42)'>click me</button>`,
    test ( answer ) {
      t.equal( answer, 42 );
    }
  });

  // Simulate click
  fire( ractive.find( 'button' ), 'click' );
});

Pull requests

All pull requests are welcome. To create a pull request, simply build your code on a branch using Ractive's dev branch as base. Then push that branch to your Github repo and submit a PR of that branch against Ractive's dev branch. To expedite the process, please follow the pull request template provided.

If in doubt, submit the PR. A PR that needs tweaking is infinitely more valuable than a request that wasn't made. Other Ractive developers will help you refine your pull request.

Contributor License Agreement

There's no contributor license agreement. Contributions are made on a common sense basis. Ractive is distributed under the MIT license, which means your contributions will be too.