Contributor Guide

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.