Getting Started

This page serves as a guide for first-time Popcode contributors, especially those who are first-time contributors to any open source project. We’ll cover the whole lifecycle of contribution, from checking out the code; to setting up your development environment; to hacking on your first project; to opening your first pull request.

Getting the code

First, you’ll need to create a fork of the Popcode repository on GitHub. A fork is your own copy of Popcode’s code base, which you are free to modify as you like. Later on, we’ll discuss how to contribute the changes you’ve made back to the official Popcode code base.

To create a fork, go to the Popcode repo on GitHub and click the Fork button. Wait for the forking process to complete, and you’ll be taken to the page for your copy of the repo.

Now that you’ve got your own copy of the code on GitHub, it’s time to get it to your computer. To start out, if you don’t have it already, download VS Code. While you can of course develop Popcode using any editor you like, Popcode has lots of built-in developer tooling in VS Code, so these instructions are written for it.

Many of the following instructions will guide you to run something in VS Code’s command palette; to access the command palette, type Command+Shift+P (on a Mac) or Ctrl+Shift+P (on Windows/Linux). This will bring up a space where you can start typing the command name, and matching commands will autocomplete.

Back on your fork on GitHub, find the green Clone or download button, click it, and copy the URL in the pop-up. Open VS Code, and in the command palette, choose Git: Clone. Paste the URL you just copied into the Repository URL prompt, then choose a location for the repository on your computer. When prompted, open the newly-cloned repository.

Setting up your development environment

Popcode comes with the ability to fully bootstrap its own development environment. To run the setup process, you’ll need a Python interpreter installed; most computers will already have this, but if yours doesn’t, you can download one here.

Note that Popcode’s development environment is completely isolated within a folder inside the Popcode project. If you have your own copies of tools like Node and Yarn installed on your computer, Popcode won’t use them and won’t interfere with them.

To begin the setup process, choose Terminal: Create New Integrated Terminal from the command palette; then at the command prompt, run:

$ tools/setup.py

This will probably take a couple minutes; when it’s done, you should see a message about installation succeeding.

Once you’ve done that, run Developer: Reload Window; this will help ensure that VS Code recognizes the custom configurations that are included in the Popcode environment.

Popcode development in VS Code is enhanced by a handful of extensions; to install them, run Extensions: Show Recommended Extensions from the command palette, which will open a list of extensions in the left sidebar. Install all of the extensions under Workspace Recommendations.

Starting your development server

When hacking on Popcode, you’ll probably be looking in two places to see how your code is working: your development instance of Popcode, and the automated tests. Let’s start with the development server.

To run the development server, we’ll introduce our first VS Code task. To run the server task, pull up the file navigation palette by typing Command+P on Mac or Ctrl+P on Windows/Linux. Type the word task into the palette (note the space afterwards), this will bring up a list of tasks to autocomplete. Run the Popcode: Start Development Server task.

The first time the development server starts, it will take a couple minutes to fully bootstrap. Subsequent starts should be much faster. Once the server is ready, you can navigate to http://localhost:3000 and confirm that there is an instance of Popcode running.

Running tests

Popcode has two test suites, a newer one written in Jest and an older one written in Karma. The Popcode team is actively working to move old tests from Karma to Jest, with the goal of eventually doing away with the Karma suite altogether. But for now, we have both.

Fortunately, it’s easy to run them side-by-side in the Popcode development environment. To do this, simply run the task Popcode: Run Tests in Watch Mode.