Development

iSar edited this page Nov 26, 2016 · 92 revisions

Getting started

Interested in contributing? Awesome! First, figure out what you'd like to do (a good place to start is the issues list and development checklist):

  • Fix a bug -- If it's not on the issues list, add it. If it's already on this issues list, assign it to yourself or comment on the issue indicating you're working on it. Go ahead and fix it and submit a PR (see below for instructions for getting set up for development). We are also in the process of adding unit tests and more inline documentation, so if the function you are fixing doesn't have these, please consider adding these as well. Submit the change to the master branch. Need help finding an issue to fix? Check out this list of bite size issues suitable for new contributors (or peruse other issue labels for topics that catch your interest).
  • Implement a new feature(s) -- First, write to hello@p5js.org to let us know you're interested! If it's not on the issues list, add it. If it's already on this issues list, assign it to yourself or comment on the issue indicating you're working on it. Note: new features will require tests and inline documentation!

    • JS Style guide:
    • Inline documentation:
    • Unit tests:
      • See the testing section for how to do this.
      • This helps ensure that the code you write keeps working far into the future when further updates and changes are made.
  • Add unit tests or documentation for existing code -- Let us know which areas you're working on so we don't duplicate efforts! Submit the change to the master branch.

  • Add examples to the examples page -- Add to the examples on the p5js.org examples page. See this guide for details.

  • Add inline examples to the ref

  • Contribute in some other way -- Write to hello@p5js.org and let us know what you're thinking! It is our intention that there should be many ways to contribute to p5.js, from writing code, to creating examples, tutorials and documentation, to thinking about workshops and education, to working on branding and design, and anything else you can dream up. Get in touch and we can talk about ways you might participate.

Setup

  1. Download and install npm. The easiest way to do this is to just install node.
  2. Install Grunt.

    npm install -g grunt-cli
    
  3. Fork and clone this library.

    git clone git@github.com:YOUR_USERNAME/p5.js.git
    
  4. Navigate into the project folder and install dependencies via npm.

    cd p5.js
    npm install
    
  5. To create the library from src, run Grunt.

    grunt
    

    If you're continuously changing files in the library, you may want to run grunt watch:quick to automatically rebuild the library for you whenever any of its source files change.

  6. Run grunt one last time to make sure all the tests pass, and submit a pull request.

Overview

lib/ Contains the concatenated p5.js and p5.min.js libraries, generated by Grunt.

src/ Contains all the source code for the library. The code is broken up into folders and files corresponding with the Processing reference page. Additionally, there is a core folder that holds constants, and internal helper functions and variables.

tests/ Contains unit testing files.

examples/ Contains code examples including a port of all of Dan Shiffman's Learning Processing, as well as an empty-empty example that demonstrates setting up a sketch, and examples related to specific tutorials.

Testing

With all new functions implemented, please include unit tests and inline documentation. A good example for how to format and write inline documentation can be seen in PImage. Examples of unit tests can be found in the test/unit directory. Directions for adding your own tests and including them are below.

The testing is done with grunt-mocha which uses mocha test framework with phantomjs. To get started:

  1. Install dependencies.

    cd p5.js/
    npm install
    
  2. Add test files corresponding to files in src (more info about Chai assert style TDD phrasing here).

  3. Link to the src and test files in test.html.
  4. Run the tests with grunt test.

Running tests in the browser

Sometimes it is useful to run tests in browser especially when trying to debug test failures. To run the tests in the browser:

  1. Run the connect server. grunt connect -keepalive
  2. Open test/test.html in your favourite web browser.

Master branch development

  1. Fork p5.js
  2. Make local changes
  3. Commit and push changes
  4. Submit a PR against the p5.js/master branch

Repositories

Alternative Setup - Docker

An alternative to setting up node, grunt, php, apache, and the p5.js & p5.js-website codebases is to use toolness/p5.js-docker. While this does require the installation of a tool called Docker, it potentially makes viewing and editing the p5 website with the latest documentation and libraries a lot easier.