documentation

developer_docs/README.md

@@ -1,106 +1,121 @@
-This folder contains various documents for developers of p5.js. This document contains the overview of how to contribute, build the library, test the code, and update the documentation.
+This folder contains various documents intended for developers of p5.js.
 
-# Getting started
+# Ways To Contribute
 
-Interested in contributing? Awesome! First, figure out what you'd like to do (a good place to start is the [issues list](https://github.com/processing/p5.js/issues)).
+## Issues
 
-* **Fix a bug** :
+Known bugs and intended new features are tracked using [GitHub issues](https://github.com/processing/p5.js/issues). If you'd like to contribute code but need suggestions about what to work on, start by looking at the existing issues. Issue [labels](https://github.com/processing/p5.js/blob/master/developer_docs/issue_labels.md) are used to sort issues into categories, such as those which are [suitable for beginners](https://github.com/processing/p5.js/labels/level%3Abeginner). If you start working on an existing issue, make sure to "assign" it to yourself so other contributors know it's being handled and can offer help. If you have discovered a bug or thought of a new feature but don't have code for it yet, you should consider submitting an issue.
 
-    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 (see below).](https://github.com/processing/p5.js/blob/master/developer_docs/#master-branch-development) 
-Need help finding an issue to fix? Check out this [list of bite size issues](https://github.com/processing/p5.js/labels/level%3Abeginner) suitable for new contributors (or peruse other [issue labels](https://github.com/processing/p5.js/blob/master/developer_docs/issue_labels.md) for topics that catch your interest).
-* **Implement a new feature** : 
+## Accompaniments
 
-    If you have an original idea about a feature, open an issue describing your idea preferably in the format provided there, and let us know you're interested! Initiate a discussion, wait for the green signal, and then assign it to yourself! _Note: new features will require tests and inline documentation._
-    - Inline documentation:
-        - [Style guide for p5.js inline docs](https://github.com/processing/p5.js/blob/master/developer_docs/inline_documentation.md) -- by formatting your documentation correctly, it will automatically show up in the p5.js reference.
-    - Unit tests:
-        - See the [testing section](https://github.com/processing/p5.js/blob/master/developer_docs/#testing) 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.
-    - Benchmarks
-        - See [Benchmarking section](https://github.com/processing/p5.js/blob/master/developer_docs/benchmarking_p5.md)
-        - Helpful for finding and implementing performance optimizations
+Aside from the code itself, you may also need to supply some combination of the following.
 
-* **Add unit tests or documentation for existing code** : 
+- [inline documentation](https://github.com/processing/p5.js/blob/master/developer_docs/inline_documentation.md) 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](https://usejsdoc.org) syntax and will be published on the p5.js website as part of the [online reference manual](https://p5js.org/reference/) 
+- [unit tests](https://github.com/processing/p5.js/blob/master/developer_docs/#testing), small pieces of code which are separate from the library and are used to verify its behavior
+- [benchmarks](https://github.com/processing/p5.js/blob/master/developer_docs/benchmarking_p5.md) to test performance
 
-    Let us know which areas you're working on so we don't duplicate efforts! [Submit the change to the master branch.](https://github.com/processing/p5.js/blob/master/developer_docs/#master-branch-development)
-    - See the [guide for p5.js inline docs](https://github.com/processing/p5.js/blob/master/developer_docs/inline_documentation.md) -- by formatting your documentation correctly, it will automatically show up in the p5.js reference (coming soon).
-    - See the [testing section](https://github.com/processing/p5.js/blob/master/developer_docs/#testing) for how to add unit tests.
+## Examples
 
-* **Add examples to the examples page** : 
+The p5.js site includes [integrated examples](http://p5js.org/examples/). You can [add more](https://github.com/processing/p5.js-website/wiki/Adding-examples), and there is an issue which lists some [desired examples](https://github.com/processing/p5.js/issues/1954).
 
-    Add to the examples on the [p5js.org examples page](http://p5js.org/examples/). See this [guide](https://github.com/processing/p5.js-website/wiki/Adding-examples) for details.
+## Other Ideas
 
-* **Add inline examples to the ref** :
+If you'd like to contribute in other ways which are not covered here, feel free to write to [[email protected]](mailto:[email protected]) 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.
 
-  * [List of examples needed](https://github.com/processing/p5.js/issues/1954)
-  * [Guide for p5.js inline docs](https://github.com/processing/p5.js/blob/master/developer_docs/inline_documentation.md) 
+# Gotchas
 
-* **Contribute in some other way** :
+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.
 
-    Write to [[email protected]](mailto:[email protected]) 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.
+## Code Syntax
 
-# Setup
+p5.js requires clean and stylistically consistent code syntax, which it enforces with [Prettier](https://prettier.io/) and [ESlint](https://eslint.org/). The rules are checked before you commit, but you can also install an [ESlint plugin](https://eslint.org/docs/user-guide/integrations#editors) for your code editor to highlight errors as soon as they appear. which will highlight problems immediately as you write your code.
 
-1. Download and install [npm](https://npmjs.org/). The easiest way to do this is to just install [node](http://nodejs.org/).
-2. [Fork and clone](https://help.github.com/articles/fork-a-repo) this library ([p5.js](https://github.com/processing/p5.js)). 
+To detect errors, run the following command in your terminal (do not type the `$` prompt):
+
+```
+$ 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](https://github.com/processing/p5.js/search?utf8=%E2%9C%93&q=prettier-ignore&type=) using an alternate syntax might make your code easier to understand. For these cases, Prettier [offers an escape hatch](https://prettier.io/docs/en/ignore.html), 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.
+
+## Unit Tests
+
+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.
+
+To run the unit tests, use Grunt.
+
+```
+$ grunt
+```
+
+Sometimes it is useful to run the tests in the browser instead of on the command line. To do this, first start the [connect](https://github.com/gruntjs/grunt-contrib-connect) server:
+
+```
+$ npm run grunt connect -keepalive
+```
+
+With the server running, you should be able to open `test/test.html` in a browser.
+
+# Development Process
+
+1. Install [node.js](http://nodejs.org/), which also automatically installs the [npm](https://www.npmjs.org) package manager.
+2. [Fork](https://help.github.com/articles/fork-a-repo) the [p5.js repository](https://github.com/processing/p5.js) into your own GitHub account.
+3. [Clone](https://help.github.com/articles/cloning-a-repository/) your new fork of the repository from GitHub onto your local computer. 
 
    ```
-   git clone https://github.com/YOUR_USERNAME/p5.js.git
+   $ git clone https://github.com/YOUR_USERNAME/p5.js.git
    ```
 
-3. Navigate into the project folder and install dependencies via npm.
+4. Navigate into the project folder and install all its necessary dependencies with npm.
 
    ```
-   cd p5.js
-   npm install
+   $ cd p5.js
+   $ npm install
    ```
 
-4. To create the complete library from source, run Grunt. 
+5. [Grunt](https://gruntjs.com/) should now be installed, and you can use it to build the library from the source code. 
 
    ```
-   npm run grunt
+   $ npm run grunt
    ```
-   **NEW** : To create the library with only certain components, use Grunt [as it is explained here.](https://github.com/processing/p5.js/blob/master/developer_docs/custom_p5_build.md)
-
-   If you're continuously changing files in the library, you may want to run `npm run grunt watch:quick` to automatically rebuild the library for you whenever any of its source files change.
-
-5. Run `npm run grunt` one last time to make sure all the tests pass, and [submit a pull request](https://help.github.com/articles/creating-a-pull-request).
-
-# Overview
+
+   If you're continuously changing files in the library, you may want to run `npm run grunt watch:quick` to automatically rebuild the library for you whenever any of its source files change without you having to first type the command manually.
 
-This [looking inside p5.js video](http://www.luisapereira.net/teaching/looking-inside-p5/) describes the tools and files used in p5.js workflow.
+6. Make some changes to the codebase and [commit](https://help.github.com/articles/github-glossary/#commit) them with Git.
 
-`lib/` Contains the concatenated p5.js and p5.min.js libraries, generated by Grunt.
+7. Run `npm run grunt` again to make sure there are no syntax errors, test failures, or other problems.
 
-`src/` Contains all the source code for the library. The code is broken up into folders and files corresponding with the [Processing reference page](http://processing.org/reference/). Additionally, there is a core folder that holds constants, and internal helper functions and variables.
+8. [Push](https://help.github.com/articles/github-glossary/#push) your new changes to your fork on GitHub.
 
-`tests/` Contains unit testing files.
-
-# Code Style
+   ```
+   $ git push
+   ```
 
-p5.js uses [Prettier](https://prettier.io/) to automatically enforce a consistent code style and [Eslint](https://eslint.org/) to find other problematic code patterns. The rules are checked both when tests are run and before you make a commit.
+9. Once everything is ready, submit your changes as a [pull request](https://help.github.com/articles/creating-a-pull-request).
 
-## Editor integration
+# Building Documentation
 
-It's a good idea to add an [Eslint plugin to your editor](https://eslint.org/docs/user-guide/integrations#editors) which will show problems as you write your code. Many of the Eslint plugins can also fix style problems while you edit your code. You can also use an integration for [Prettier](https://prettier.io/), but the Eslint plugins provide most of the same features and more.
+Inline comments in p5.js are built into the public-facing [reference manual](https://p5js.org/reference/). You can also view this locally:
 
-## Automatic style fixing
+```
+$ npm run docs:dev
+```
 
-`npm run lint:fix` will format your code so that it follows the code style rules. You can check for style errors / code problems without fixing them by running `npm run lint`.
+# Overview
 
-## My commit got rejected ?! 
-Whenever you make a commit, Eslint and Prettier will check that your code follows the style rules and reject commits that break the rules. The error often looks like this:
-```
-eslint found some errors. Please fix them and try committing again.
+This [looking inside p5.js video](http://www.luisapereira.net/teaching/looking-inside-p5/) describes the tools and files used in p5.js workflow.
 
-✖ 3 problem (2 error, 1 warnings)
-  1 error, 1 warnings potentially fixable with the `--fix` option.
-```
+`lib/` Contains the concatenated p5.js and p5.min.js libraries, generated by Grunt.
 
-Errors or warnings that are ``fixable with the `--fix` option`` are fixed by running `npm run lint:fix`. 
+`src/` Contains all the source code for the library. The code is broken up into folders and files corresponding with the [Processing reference page](http://processing.org/reference/). Additionally, there is a core folder that holds constants, and internal helper functions and variables.
 
-## My code needs a special format!
-In [some special cases](https://github.com/processing/p5.js/search?utf8=%E2%9C%93&q=prettier-ignore&type=) your code needs special formatting to look more clear. Prettier [offers an escape hatch](https://prettier.io/docs/en/ignore.html) to ignore a block of code from being formatted, via the `// prettier-ignore` comment. Use with caution!
+`tests/` Contains unit testing files.
 
 # Testing
 
@@ -120,36 +135,6 @@ To get started:
 3. Link to the src and test files in `test.html`. 
 4. Run the tests with `npm run grunt`.
 
-## Building and testing the Reference Docs & Examples
-
-This will build the p5.js library, generate the documentation files, run a web server, and open a browser to the main documentation page.
-
-    ````
-    npm run docs:dev
-    ````
-
-## 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. ```npm run grunt connect -keepalive```
-2. Open test/test.html in your favourite web browser.
-
-# Master branch development
-
-1. Fork p5.js
-2. Create a feature branch: `git checkout -b my_branch`
-3. Make local changes
-4. Commit and push changes. When you first attempt to push your feature branch, `git` will give you instructions on how to have your local branch track a similarly-named one on Github.
-5. Submit a PR against the `p5.js/master` branch
-6. checkout the master branch: `git checkout master`
-
-## Bringing your master branch up-to-date
-
-1. Make sure you have no uncommitted changes, or any additional commits in your master branch. The following commands will discard any changes you have made.
-2. `git checkout master`
-3. `git fetch`
-4. `git reset --hard upstream/master`
-5. `git push -f`
 
 # Repositories
 
@@ -166,4 +151,5 @@ An alternative to setting up node, grunt, php, apache, and the p5.js & p5.js-web
 
 # p5.js API JSON file
 
-[This file](https://p5js.org/reference/data.json) can be used for auto-complete. This [gist](https://gist.github.com/jonohayon/b059a029755f84f42b29f005323ec165) explains how to parse the file. Note that the data.json file is generated when the `npm run grunt` command is run, it is found on the p5js.org website but is not included in the repo.
+[This file](https://p5js.org/reference/data.json) can be used for auto-complete. This [gist](https://gist.github.com/jonohayon/b059a029755f84f42b29f005323ec165) explains how to parse the file. Note that the data.json file is generated when the `npm run grunt` command is run, it is found on the p5js.org website but is not included in the repo.
+