-
Notifications
You must be signed in to change notification settings - Fork 138
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.
Our first task is to have a working development environment on your laptop.
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.
Our last step will make it easy for Git to find the official Popcode repository, so you can easily pull in the latest changes to your copy. From the command palette, run Git: Add Remote. Call the remote upstream, and for the remote URL enter https://github.com/popcodeorg/popcode.git. Finally, run the command Git: Fetch From All Remotes
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.pyThis 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.
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.
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. This will open a split-screen view with the Jest tests in one pane and the Karma tests in the other. Both tests will be in watch mode, meaning that they will run once when you start the task, and then run again each time you edit a file. As with the development server, the first run takes much longer than subsequent ones.
Now that you’ve got a working development environment, it’s time to start writing code!
If you’ve got a feature you’d like to build, enhancement you’d like to make, or bug you’d like to fix, by all means go for it. But if you’re just looking to get involved without a prior idea of what exactly you want to work on, your best bet is to head to the #dev channel on the Popcode Slack team and introduce yourself. The Popcode contributors are happy to help new people find a project that fits their interests and desired level of technical challenge.
When working on a project with other developers—in fact, even when working on your own—it’s a good idea to create a new git branch for each feature, bugfix, etc. Your branch will track all the changes you make in order to complete your goal, without any unrelated work getting mixed in; you can make more than one branch if you’re working on more than one project at the same time.
First, you’ll need to think of a branch name—Popcode doesn’t have any specific conventions for branch names, so you should just choose something descriptive—for instance, if I were building support for TypeScript in Popcode, I might call my branch typescript-support.
To create the new branch, choose the command (not task) Git: Create Branch From… from the command palette. This will ask you first to enter your branch name, and then a “ref to create the branch from”. For this last question, you will always want to select master, which ensures that your branch doesn’t get mixed up with feature work on a different branch.
Finally, let’s make sure our new branch is 100% up to date with the latest Popcode code base. To do this, you’ll run the command Git: Pull From…. When prompted, choose upstream for the remote, and upstream/master for the branch.