diff --git a/contributor_docs/README.md b/contributor_docs/README.md index 45d4cc3003..56f4de4984 100644 --- a/contributor_docs/README.md +++ b/contributor_docs/README.md @@ -14,10 +14,10 @@ We are prioritizing work that expands access (inclusion and accessibility) to p5 The overarching p5.js project includes some repositories other than this one: -- [p5.js](https://github.com/processing/p5.js): This repository contains the source code for the p5.js library. The [user-facing p5.js reference manual](https://p5js.org/reference/) is also generated from the [JSDoc](http://usejsdoc.org/) comments included in this source code. It is maintained by [Qianqian Q Ye](https://github.com/qianqianye) and [evelyn masso](https://github.com/outofambit). -- [p5.js-website](https://github.com/processing/p5.js-website) This repository contains most of the code for the [p5.js website](http://p5js.org), with the exception of the reference manual. It is maintained by [Kenneth Lim](https://github.com/limzykenneth), [Qianqian Q Ye](https://github.com/qianqianye) and [evelyn masso](https://github.com/outofambit). -- [p5.js-sound](https://github.com/processing/p5.js-sound) This repository contains the p5.sound.js library. It is maintained by [Jason Sigal](https://github.com/therewasaguy). -- [p5.js-web-editor](https://github.com/processing/p5.js-web-editor) This repository contains the source code for the [p5.js web editor](https://editor.p5js.org). It is maintained by [Cassie Tarakajian](https://github.com/catarak). Note that the older [p5.js editor](https://github.com/processing/p5.js-editor) is now deprecated. +- **[p5.js](https://github.com/processing/p5.js)**: This repository contains the source code for the p5.js library. The [user-facing p5.js reference manual](https://p5js.org/reference/) is also generated from the [JSDoc](http://usejsdoc.org/) comments included in this source code. It is maintained by [Qianqian Q Ye](https://github.com/qianqianye) and [evelyn masso](https://github.com/outofambit). +- **[p5.js-website](https://github.com/processing/p5.js-website)**: This repository contains most of the code for the [p5.js website](http://p5js.org), with the exception of the reference manual. It is maintained by [Kenneth Lim](https://github.com/limzykenneth), [Qianqian Q Ye](https://github.com/qianqianye) and [evelyn masso](https://github.com/outofambit). +- **[p5.js-sound](https://github.com/processing/p5.js-sound)**: This repository contains the p5.sound.js library. It is maintained by [Jason Sigal](https://github.com/therewasaguy). +- **[p5.js-web-editor](https://github.com/processing/p5.js-web-editor)**: This repository contains the source code for the [p5.js web editor](https://editor.p5js.org). It is maintained by [Cassie Tarakajian](https://github.com/catarak). Note that the older [p5.js editor](https://github.com/processing/p5.js-editor) is now deprecated. @@ -25,22 +25,22 @@ The overarching p5.js project includes some repositories other than this one: There are a lot of files here! Here's a brief overview. It can be confusing, but you don't need to understand every file in the repository to get started. We recommend beginning in one area (for example, fixing some inline documentation), and working your way outwards to exploring more. Luisa Pereira's [Looking Inside p5.js](https://www.luisapereira.net/teaching/materials/processing-foundation) also gives a video tour of the tools and files used in the p5.js workflow. -- `contributor_docs/` contains documents that explain practices and principles for contributors -- `docs/` does not actually contain docs! Rather, it contains the code used to *generate* the [online reference manual](https://p5js.org/reference/). -- `lib/` contains an empty example and the p5.sound add-on, which is periodically updated via pull request from the [p5.js-sound repository](https://github.com/processing/p5.js-sound). This is also where the built p5.js library gets placed after being compiled to a single file using [Grunt](https://gruntjs.com/). It does not need to be checked into the github repository when you make a pull request. -- `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. Most folders have their own readme.md files inside to help you find your way around. -- `tasks/` contains scripts which perform automated tasks related to the build, deployment, and release of new versions of p5.js. -- `tests/` contains unit tests which ensure the library continues to function correctly as changes are made. -- `utils/` might contain additional files useful for the repository, but generally you can ignore this directory. +- 📁`contributor_docs/` contains documents that explain practices and principles for contributors +- 📁`docs/` does not actually contain docs! Rather, it contains the code used to *generate* the [online reference manual](https://p5js.org/reference/). +- 📁`lib/` contains an empty example and the p5.sound add-on, which is periodically updated via pull request from the [p5.js-sound repository](https://github.com/processing/p5.js-sound). This is also where the built p5.js library gets placed after being compiled to a single file using [Grunt](https://gruntjs.com/). It does not need to be checked into the github repository when you make a pull request. +- 📁`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. Most folders have their own readme.md files inside to help you find your way around. +- 📁`tasks/` contains scripts which perform automated tasks related to the build, deployment, and release of new versions of p5.js. +- 📁`tests/` contains unit tests which ensure the library continues to function correctly as changes are made. +- 📁`utils/` might contain additional files useful for the repository, but generally you can ignore this directory. # Documentation -We realize the documentation is the most important part of this project. Poor documentation is one of the main barriers to access for new users and contributors, making the project less inclusive. The [contributing_documentation.md](./contributing_documentation.md) page gives an in-depth overview of getting started with documentation. The documentation for p5.js can be found in a few main places: +We realize the documentation is the most important part of this project. Poor documentation is one of the main barriers to access for new users and contributors, making the project less inclusive. The 📄[`contributing_documentation.md`](./contributing_documentation.md) page gives an in-depth overview of getting started with documentation. The documentation for p5.js can be found in a few main places: -- The [p5js.org/reference](https://p5js.org/reference/) is generated from [inline documentation](./inline_documentation.md) in the source code itself. This includes the text descriptions and parameters as well as the accompanying code snippet examples. We place all this inline to keep the code and documentation closely linked, and to reinforce the idea that contributing to documentation is as important (if not more) than contributing to the code. When the library gets built, it checks the inline documentation and examples to ensure they match up with the way the code behaves. To contribute, you can start by looking at the [inline_documentation.md](./inline_documentation.md) page. -- The [p5js.org/examples](http://p5js.org/examples) page contains longer examples that can be useful for learning p5.js. To contribute, you can start by looking at the [adding_examples.md](https://github.com/processing/p5.js-website/blob/main/contributor_docs/Adding_examples.md) page. +- The [p5js.org/reference](https://p5js.org/reference/) is generated from [inline documentation](./inline_documentation.md) in the source code itself. This includes the text descriptions and parameters as well as the accompanying code snippet examples. We place all this inline to keep the code and documentation closely linked, and to reinforce the idea that contributing to documentation is as important (if not more) than contributing to the code. When the library gets built, it checks the inline documentation and examples to ensure they match up with the way the code behaves. To contribute, you can start by looking at the 📄[`inline_documentation.md`](./inline_documentation.md) page. +- The [p5js.org/examples](http://p5js.org/examples) page contains longer examples that can be useful for learning p5.js. To contribute, you can start by looking at the 📄[`adding_examples.md`](https://github.com/processing/p5.js-website/blob/main/contributor_docs/Adding_examples.md) page. - The [p5js.org/learn](https://p5js.org/learn) page contains tutorials to help you learn concepts of p5.js and programming. To contribute, you can start by looking at the [p5.js guide to contributing to tutorials](https://p5js.org/learn/tutorial-guide.html). - You'll notice the p5.js website currently supports a few different languages. This is called internationalization (or i18n for short). You can read more about this documentation on the [i18n_contribution](https://github.com/processing/p5.js-website/blob/main/contributor_docs/i18n_contribution.md) page. @@ -52,13 +52,13 @@ We realize the documentation is the most important part of this project. Poor do * 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)](./preparing_a_pull_request.md) against the p5.js main 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". +* Once you have completed your work on this issue, [submit a pull request (“PR”)](./preparing_a_pull_request.md) against the p5.js main 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](https://www.codetriage.com/processing/p5.js). [![Open Source Helpers](https://www.codetriage.com/processing/p5.js/badges/users.svg)](https://www.codetriage.com/processing/p5.js) -* The [organization.md](https://github.com/processing/p5.js/blob/main/contributor_docs/organization.md) file gives a high-level overview of how issues can be organized and the decision making processes around them. Please feel welcome to get involved with this if you are interested. +* The 📄[`organization.md`](https://github.com/processing/p5.js/blob/main/contributor_docs/organization.md) file gives a high-level overview of how issues can be organized and the decision making processes around them. Please feel welcome to get involved with this if you are interested. @@ -136,7 +136,7 @@ $ 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. -Here is a quick summary of code style rules. Please note that this list may be incomplete, and it's best to refer to the [.prettierrc](https://github.com/processing/p5.js/blob/main/.prettierrc) and [.eslintrc](https://github.com/processing/p5.js/blob/main/.eslintrc) files for the full list. +Here is a quick summary of code style rules. Please note that this list may be incomplete, and it's best to refer to the 📄[`.prettierrc`](https://github.com/processing/p5.js/blob/main/.prettierrc) and 📄[`.eslintrc`](https://github.com/processing/p5.js/blob/main/.eslintrc) files for the full list. * ES6 code syntax is used * Use single quotes (rather than double quotes) @@ -145,7 +145,7 @@ Here is a quick summary of code style rules. Please note that this list may be i * 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. +* 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 @@ -155,7 +155,7 @@ Here is a quick summary of code style rules. Please note that this list may be i ## Unit Tests -Unit tests are small pieces of code which are created as complements to the primary logic and perform validation. The [unit_testing.md](./unit_testing.md) page gives more information about working with unit tests. 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. +Unit tests are small pieces of code which are created as complements to the primary logic and perform validation. The 📄[`unit_testing.md`](./unit_testing.md) page gives more information about working with unit tests. 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 make sure you have installed the project's dependencies. @@ -182,15 +182,15 @@ $ 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](http://www.chaijs.com/api/assert/) 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. +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](http://www.chaijs.com/api/assert/) 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. # Miscellaneous -- There are other files in the [contributor_docs/](https://github.com/processing/p5.js/tree/main/contributor_docs) folder that you might explore. They pertain to contributing to specific areas of this project, both technical and non-technical. +- There are other files in the 📁[`contributor_docs/`](https://github.com/processing/p5.js/tree/main/contributor_docs) folder that you might explore. They pertain to contributing to specific areas of this project, both technical and non-technical. - [Looking Inside p5.js](https://www.luisapereira.net/teaching/materials/processing-foundation) is a video tour of the tools and files used in the p5.js development workflow. - [This video from The Coding Train](https://youtu.be/Rr3vLyP1Ods) :train::rainbow: gives an overview of getting started with technical contribution to p5.js. - The p5.js [Docker image](https://github.com/toolness/p5.js-docker) can be mounted in [Docker](https://www.docker.com/) and used to develop p5.js without requiring manual installation of requirements like [Node](https://nodejs.org/) 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](https://p5js.org/reference/data.json) 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. +- The build process for the p5.js library generates a [JSON data file](https://p5js.org/reference/data.json) 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. - p5.js has recently migrated to [ES6](https://en.wikipedia.org/wiki/ECMAScript#6th_Edition_-_ECMAScript_2015). To see how this transition could effect your contribution please visit [ES6 adoption](./es6-adoption.md).