Skip to content

Latest commit

 

History

History
90 lines (56 loc) · 6.49 KB

dev-environment-setup.md

File metadata and controls

90 lines (56 loc) · 6.49 KB
Raw

Getting Your Dev Environment Started

This guide will provide you with the information you need to be able to get started on your development journey.

Contents

Text Editor

VSCode is our preferred text editor. We advise that you follow the installation instructions provided by Microsoft. Installation instructions can be found here for Mac users and here for Windows users.

Useful VSCode Extensions to Install

You can browse and install extensions from within VS Code. Simply bring up the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of VS Code or the View: Extensions command (⇧+⌘+X) on Mac or (shift+alt+x) on Windows.

Below are some useful extensions that we recommend using with Carbon:

  • Auto Close Tag - automatically adds the closing tags for HTML and XML.
  • Auto Rename Tag - automatically renames HTML and XML tags.
  • CodeSnap - lets you take screenshots of your code and save them to a clipboard.
  • Code Spell Checker - basic spelling checker that works well with many file types. There is an additional extension for getting the British English dictionary.
  • ESLint - a code quality tool that checks your code for syntax errors and can automatically fix the syntax errors.
  • GitLens - provides a list of complementary features for use with git repositories, such as in-editor file annotations identifying who changed a line of code last.
  • markdownlint - linter and style checker for markdown files.
  • MDX - official extension for supporting MDX files.
  • Package Json Upgrade - adds in-editor file annotations to package.json stating if an installed package has a newly available version.
  • Playwright Test for VSCode - for running Playwright tests directly within VSCode.
  • Total TypeScript - provides human-readable hints for TypeScript errors that are difficult to decipher.
  • vscode-styled-components - this extension helps with the readability of the code for styled-components. The tool highlights syntax and reports any syntax errors in the code.

Installing Node.js, NPM, and Git

Node.js & NPM

NOTE: Carbon requires all contributors be on Node version 20 ("iron").

The recommended way to install Node and npm is using Node Version Manager (nvm). Once you have installed nvm, you should run:

nvm install lts/iron

which will install the correct version of Node and npm. You can verify the installed versions using node --version and npm --v.

If you are already a nvm user, you can also do nvm use which will automatically switch to the correct Node and npm versions.

Git

To find out if you already have a version of Git installed on your machine, simply run git --version in your terminal or command line. If you have Git installed, you will receive a console output similar to this: git version 2.23.0

If you do not have Git already installed, you can download the latest version of Git from here.

New to Git?

If you are new to Git, it can be a little overwhelming at first. Luckily there are a lot of dedicated information and training for Git. Atlassian have an easy to understand and informative article that explains the Feature Branch workflow.

Pluralsight also offers excellent training courses ranging from beginner to advanced users. A good place to start is with the How Git Works training course. This will start you off with the very basic principles of Git.

Git Alias

You need to add the following to ~/.gitconfig:

[alias]
        pr = "!f() { git fetch -fu ${2:-origin} refs/pull/$1/head:pr/$1 && git checkout pr/$1; }; f"
        pr-clean = "!git checkout master ; git for-each-ref refs/heads/pr/* --format=\"%(refname)\" | while read ref ; do branch=${ref#refs/heads/} ; git branch -D $branch ; done"

This allows you to review PRs very easily. For example, if you are reviewing #2408, you can use git pr 2408 which will check out a new branch named pr/2408. This gives you the ability to review, change branches, merge and make experimental changes. The second command git pr-clean removes all branches that start with pr/. This is a useful for housekeeping of branches.

GPG Verification

We strongly encourage our contributors to verify their commits with a GPG key. To set this up, please follow these instructions from GitHub to enable GPG commit signing.

Then add this to your profile (i.e~/.zshrc or ~/.bashrc) so gpg-agent can prompt for your passphrase:

export GPG_TTY=$(tty)

Then execute this command to sign all of your commits by default:

$ git config --global commit.gpgsign true

Restart of gpg-agent may be required. Use the command below to kill it (it will start next time its needed):

$ gpgconf --kill gpg-agent