Hello! Thanks for your interest in contributing to p5.js! You can get started with some different ways of contributing here. This folder contains various documents intended for developers of p5.js.
Project Directory Structure
src/contains all the source code for the library, which is topically organized into separated modules. This is what you'll work on if you are changing p5.js.
lib/contains the final version of p5.js intended for users to load in their sketches and projects, included in both compressed and uncompressed forms. This is the output when the source code modules are compiled to a single file by Grunt.
contributor_docs/contains various Markdown documents that are likely to be useful to developers of p5.js, in particular because they explain practices and principles.
docs/does not actually contain docs! Rather, it contains the code used to generate the online reference manual.
tests/contains unit tests which ensure the library continues to function correctly as changes are made.
tasks/contains scripts which perform automated tasks related to the build, deployment, and release of new versions of p5.js.
patches/might contain Git patches from time to time, but in almost all cases you can completely ignore this directory.
How To Contribute
Known bugs and intended new features are tracked using GitHub issues. Issue labels are used to sort issues into categories, such as those which are suitable for beginners. If you'd like to start working on an existing issue, comment on the issue that you plan to work on it so other contributors know it's being handled and can offer help. Once you have completed your work on this issue, submit a pull request (PR) against the p5.js master branch. In the description field of the PR, include "resolves #XXXX" tagging the issue you are fixing. If the PR addresses the issue but doesn't completely resolve it (ie the issue should remain open after your PR is merged), write "addresses #XXXX".
If you discover a bug or have an idea for a new feature you'd like to add, begin by submitting an issue. Please do not simply submit a pull request containing the fix or new feature without making an issue first, we will probably not be able to accept it. Once you have gotten some feedback on the issue and a go ahead to address it, you can follow the process above to contribute the fix or feature.
You can triage issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to subscribe to p5.js on CodeTriage.
Aside from the code itself, you may also need to supply some combination of the following.
- inline documentation in the form of code comments, which explain the code both to other developers and to users. Many of these comments must conform to JSDoc syntax and will be published on the p5.js website as part of the online reference manual
- unit tests, small pieces of code which are separate from the library and are used to verify its behavior
If you'd like to contribute in other ways which are not covered here, feel free to write to firstname.lastname@example.org and let us know what you're thinking! Aside from working on this codebase, we can always use help with things like documentation, tutorials, workshops, educational materials, branding, and design. Get in touch and we can talk about ways you might participate.
The developer tooling included with the p5.js codebase is intentionally very strict about some things. This is a good thing! It makes everything consistent, and it will encourage you to be disciplined. This means you may try to change something only to have your commit rejected by the project, but don't get discouraged; even seasoned p5.js developers get caught by this stuff all the time. Typically the problem will be in one of two areas.
p5.js requires clean and stylistically consistent code syntax, which it enforces with Prettier and ESlint. The rules are checked before you commit, but you can also install an ESlint plugin for your code editor to highlight errors as soon as you type them, which will probably help you along as you are coding and saves you the hassle of a failed Git commit. In general, we err on the side of flexibility when it comes to code style, in order to lower the barriers to participation and contribution.
To detect errors, run the following command in your terminal (do not type the
$ npm run lint
Some syntax errors can be automatically fixed:
$ npm run lint:fix
Sticking with the established project style is usually preferable, but occasionally using an alternate syntax might make your code easier to understand. For these cases, Prettier offers an escape hatch, the
// prettier-ignore comment, which you can use to make granular exceptions. Try to avoid using this if you can, because there are good reasons for most of the style preferences enforced by the linting.
- ES6 code syntax is used
- Use single quotes (rather than double quotes)
- Indentation is done with two spaces
- All variables defined in the code should be used at least once, or removed completely
- Do not compare x == true or x == false. Use (x) or (!x) instead. x == true, is certainly different from if (x)! Compare objects to null, numbers to 0 or strings to "", if there is chance for confusion.
- Comment your code whenever there is ambiguity or complexity in the function you are writing
- See the Mozilla JS practices as a useful guide for more styling tips
Unit tests are small pieces of code which are created as complements to the primary logic and perform validation. If you are developing a major new feature for p5.js, you should probably include tests. Do not submit pull requests in which the tests do not pass, because that means something is broken.
In order to run unit tests, you'll need to have previously installed the project's dependencies.
$ npm ci
This will install all the dependencies for p5.js; briefly, the most important dependencies specific to unit testing include:
- Mocha, a powerful testing framework that executes individual test files which are specific to p5.js
- mocha-chrome, a mocha plugin that runs mocha tests using headless Google Chrome
Once the dependencies are installed, use Grunt to run the unit tests.
Sometimes it is useful to run the tests in the browser instead of on the command line. To do this, first start the connect server:
$ npm run dev
With the server running, you should be able to open
test/test.html in a browser.
A complete guide to unit testing is beyond the scope of the p5.js documentation, but the short version is that any major changes or new features implemented in the source code contained in the
src/ directory should also be accompanied by test files in the
test/ directory that can be executed by Mocha to verify consistent behavior in all future versions of the library. When writing unit tests, use the Chai.js reference as a guide for phrasing your assertion messages so that any errors caught by your tests in the future will be consistent and consequently easier for other developers to understand.
Clone your new fork of the repository from GitHub onto your local computer.
$ git clone https://github.com/YOUR_USERNAME/p5.js.git
Navigate into the project folder and install all its necessary dependencies with npm.
$ cd p5.js $ npm ci
Grunt should now be installed, and you can use it to build the library from the source code.
$ npm run grunt
If you're continuously changing files in the library, you may want to run
npm run devto automatically rebuild the library for you whenever any of its source files change without you having to first type the command manually.
Make some changes locally to the codebase and commit them with Git.
$ git add -u $ git commit -m "YOUR COMMIT MESSAGE"
npm run gruntagain to make sure there are no syntax errors, test failures, or other problems.
Push your new changes to your fork on GitHub.
$ git push
Once everything is ready, submit your changes as a pull request.
This process is also covered in a video by The Coding Train.
Inline comments in p5.js are built into the public-facing reference manual. You can also view this locally:
$ npm run docs:dev
The overarching p5.js project includes repositories other than this one.
- p5.js: This repository contains the source code for the p5.js library. The user-facing p5.js reference manual is also generated from the JSDoc comments included in this source code. It is maintained by Lauren McCarthy.
- website This repository contains most of the code for the p5.js website, with the exception of the reference manual. It is maintained by Lauren McCarthy.
- sound This repository contains the p5.sound.js library. It is maintained by Jason Sigal.
- web editor: This repository contains the source code for the p5.js web editor. It is maintained by Cassie Tarakajian. Note that the older p5.js editor is now deprecated.
- Looking Inside p5.js is a video tour of the tools and files used in the p5.js development workflow.
- The p5.js Docker image can be mounted in Docker and used to develop p5.js without requiring manual installation of requirements like Node or otherwise affecting the host operating system in any way, aside from the installation of Docker.
- The build process for the p5.js library generates a json data file which contains the public API of p5.js and can be used in automated tooling, such as for autocompleting p5.js methods in an editor. This file is hosted on the p5.js website, but it is not included as part of the repository.