Contributor Guide - q5js/q5.js GitHub Wiki

This guide is intended for people that want to contribute to q5.

To learn how to use q5, visit q5js.org.

The website you're currently on is called GitHub, it was created for people to share and collaborate on coding projects, often called "repos" (short for repositories).

The easiest way to contribute to q5, or any other repo on GitHub, is by creating a GitHub account and editing files directly on this site. Then you can submit a pull request (PR), which is a request that a maintainer of a project pulls your changes into the main branch of the repo.

Would you like to contribute to q5.js itself, its documentation, or the q5js.org website? See the relevant sections on this page for more info.

Please read the Code of Conduct before contributing. 🤝

q5 Coding Principles

Code is a language art that can be subjectively judged by its effectiveness at communicating its functionality to humans. Code can also be objectively measured by its performance. Since JavaScript is served over a network, size is a factor as well.

Therefore, we strive to balance code readability with brevity and performance!

"Make everything as simple as possible, but not simpler" - Albert Einstein

Don't overcomplicate things that can be made simpler, but also don't oversimplify.

"So the writer who breeds more words than he needs, is making a chore for the reader who reads" - Dr. Seuss

Less is more and Don't Repeat Yourself, keep code concise through reasonable use of abstractions instead of duplication.

"Only the best is good enough!" - Ole Kirk Christiansen, founder of LEGO

Often during development you can start with some code that "just works" but should iterate on it until you find a more perfect solution through experimentation.

Contributing to the Source Code of q5.js

The q5.js file in this repo is generated by putting all the "default bundle" files from the src folder into one file. Therefore, you shouldn't edit the q5.js file directly, stick to editing the files in src.

Git keeps track of any changes to a repo. So in order to keep a clean change log, be careful not to change the formatting of files and follow q5's code style (see below).

Every major open-source project has its own style guide: a set of conventions (sometimes arbitrary) about how to write code for that project. It's much easier to understand a large codebase when it has a consistent style. - Google Style Guides

If you're using a code editor app, it may be helpful to turn auto-formatting off while working on q5.

q5 Style Guide

  • use tabs instead of spaces
  • use single quotes instead of double quotes
  • use camelCase for variable and function names
  • use for or for..of loops instead of Array.forEach

Contributing to q5js.org

q5js.org uses Markdown and basic HTML/CSS/JS.

See the lang (languages) folder, inside there are folders named with two character language codes, and inside those are markdown files (with the .md file extension).

Markdown enables you to write formatted text, without using a word processor, yet it's easier to write compared to HTML. Take a look at this guide on how to write markdown: https://www.markdownguide.org/cheat-sheet/

Communicating with Developers

Many developers prefer to communicate on messaging platforms like Discord and Slack, which support markdown syntax. That way they can send code to each other with syntax highlighting.

Join the q5 team in the "#dev" channel on the q5 community Discord.

Local Development

All you need is a GitHub account to edit files on this site right in your web browser. Yet, most professional developers will download repos to their own computer to edit them "locally". Local development enables you to edit files using an editor app like Visual Studio Code that you can customize based on your own personal preferences and needs.

GitHub uses a program called Git, which keeps track of changes to a repo's files each time a "commit" is "pushed". This enables developers to edit a repo and then easily download, "pull", changes from other developers working on the same project.

  • install the Google Chrome web browser for fastest overall performance
  • Windows users need to install Git
  • macOS users need to install Git via the command xcode-select --install in the Terminal app
  • install the Visual Studio Code editor

Setup

Open the Git Bash app on Windows or the Terminal app on macOS.

A terminal lets you navigate your computer and run programs via text based commands instead of via the graphical user interfaces of programs like File Explorer or Finder.

Let's use the cd command to go to a folder that you want your code projects to be in, for example your "Documents" or "Desktop" folder.

cd ~/Desktop

The command git clone downloads a git repo to your computer.

git clone https://github.com/q5js/q5.js.git

When the download is finished, open the Visual Studio Code app (commonly called "VSCode") and open the q5 folder in it.

Install Extensions for VSCode

In the Activity Bar on the left side of VSCode click the extension icon, which looks like one box being separated from three other boxes, you can search for the following extensions or use the links below to install them.

"Live Server" auto-refreshes the browser when you make changes to your code. https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer

"Prettier" is an extension that will automatically format your code for you when you save it so you won't have to worry about doing proper indentation and formatting yourself! https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

"Markdown Preview Enhanced" is a great extension for previewing Markdown files. https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced

"vscode-color-picker" is a great extension for picking colors in JavaScript files. https://marketplace.visualstudio.com/items?itemName=AntiAntiSepticeye.vscode-color-picker

VSCode Settings

If you want you can use the exact VSCode settings that I use when working on q5.

Press F1 on your keyboard (hold Fn then press F1 on macOS). Search the menu for "Preferences: Open Settings (JSON)". Add these settings to VSCode's settings.json file:

"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.guides.bracketPairs": true,
"editor.bracketPairColorization.enabled": true,
"editor.formatOnPaste": true,
"editor.minimap.enabled": false,
"editor.tabSize": 2,
"editor.insertSpaces": false,
"editor.formatOnSave": true,
"editor.wordWrap": "on",
"explorer.confirmDelete": false,
"explorer.confirmDragAndDrop": false,
"files.insertFinalNewline": true,
"files.trimFinalNewlines": true,
"prettier.jsxSingleQuote": true,
"prettier.singleQuote": true,
"prettier.trailingComma": "none",
"prettier.useTabs": true,
"prettier.printWidth": 120,
"diffEditor.wordWrap": "on",
"liveServer.settings.donotShowInfoMsg": true,
"editor.glyphMargin": false,
"editor.folding": false