Contributor Guide - q5js/q5.js GitHub Wiki

This guide is intended for people that want to contribute to the development of 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).

You can contribute to q5 or any other repo on GitHub by editing the files directly on the website, however 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 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.

Local Development

  • 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.

Working with Markdown files

Many text files you encounter on GitHub are written in Markdown format, with the .md file extension.

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

The best part about markdown is that code can be embedded between triple backticks.

alert('Wow! Markdown is great!');

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.

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

Try using the same VSCode settings that I use. If you don't like them, you can always change them later.

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

Documentation

q5's documentation uses a library made by @Tezumie called Simple-Docs.

Code Style Guide

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. “Style” covers a lot of ground, from "use camelCase for variable names" (aesthetic) to "never use global variables" (functional). - Google Style Guides

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, the q5 team strives to balance code readability with brevity and performance!

Principles

Keep it Simple! Usually the best, simplest solution to a problem is not immediately obvious.

Good enough isn't good enough! We strive for excellence when developing q5. Often during development you can start with some code that "just works" and iterate on it until you find a more perfect solution through experimentation.

Don't Repeat Yourself! keep code concise through reasonable use of abstractions instead of duplication.

Styles

  • Use standard for or for..of loops instead of Array.forEach (slow)