Getting Started - popcodeorg/popcode GitHub Wiki

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 help

Before we dive in, remember that if you get stuck at any point, you can jump into the #dev channel on the Popcode Slack team; all questions are welcome!

Setting up

Our first task is to have a working development environment on your laptop.

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.

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

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

Writing a feature

Now that you’ve got a working development environment, it’s time to start writing code!

Picking a project

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.

Creating a branch

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.

Hacking on the project

If you haven’t got them running yet, be sure to start the Popcode: Start Development Server and Popcode: Run Tests in Watch Mode tasks. Head to http://localhost:3000 to access your local instance of Popcode.

While each project will require a unique path of exploration of the codebase to get a handle on, there are some tools and resources that will be helpful to just about anyone who is new to Popcode’s tech stack. Start with two fantastic Chrome extensions: the React Developer Tools and Redux DevTools. These extensions will give you a detailed view of what is happening under the hood of Popcode as you use it.

Popcode is built on a few core technologies; the two big ones are React and Redux. React is used to construct the visible contents of the page, and to set up handling of user interactions like clicks. If you’re brand new to React, I recommend the React tutorial, the guide to main concepts, and the thinking in React sections of the official React documentation. Once you’re comfortable with the basic concepts of React, open the React Components tab in your Chrome developer tools and explore a bit—you can use the selector tool to click on the page and see what component renders that part of the page; or just poke around the component hierarchy.

Redux is where Popcode keeps all application state, information such as:

What is the current project? What are the contents of its HTML, CSS, and JS code?
What errors exist in the current code?
What user account is logged in, if any?
Which menu in the top bar is open, if any?

While React and Redux are separate projects, it’s very common to use them together. If you’re new to Redux, I recommend reading the Introduction and Basic Tutorial in the Redux documentation, as well as the Basic Tutorial in the React Redux documentation. Once you’re comfortable with how Redux works, open up the Redux tab of the Chrome developer tools, and then play around with Popcode—check out which actions get dispatched as you use the application, and how the state changes in response.

One last important piece of the stack is redux-logic, which provides a framework for writing business logic that is closely tied to the Redux store; in particular, any time we need to do asynchronous work like making a network request, a logic is the right place to do that. A basic logic will consume a particular action; do some (usually asynchronous) work; and then dispatch a new action to indicate that the work is complete. I don’t find the README for redux-logic particularly easy to follow; instead I recommend perusing this article for an introduction to the library.

Note: Popcode is currently in the process of migrating to redux-logic from another tool that serves a similar purpose, called redux-saga. All new business logic should be written as logics, but you may find the existing business logic you’re looking for in a saga.

Testing your code

As you work on your project, you’ll probably find it easiest to check your work by testing it out on your local development instance, which is just fine! But Popcode also has an automated test suite, and we try to make sure certain parts of the codebase are fully tested. In particular, if you are adding or changing reducers, logics, or validations, you should make sure to write unit tests covering your changes. Popcode uses Jest for unit testing, and you’ll find tests in various __tests__ directories, colocated with the modules the tests are written for.

Note: Popcode is also currently in the process of migrating to Jest from a suite based on Tape and Karma; the majority of existing tests are in the legacy suite. This is why the test task starts up two separate watch processes. Tape/Karma tests can be found in the test/unit directory, and it’s fine to make modest modifications to them to cover changes in existing behavior; but all new tests should be written using Jest.

Contributing your work

Once you’ve got your new code working the way you want, it’s time to get it into the official Popcode code base.

Preparing to submit

If you haven’t yet, commit your changes to your local repository; the fastest way to do this is to run the Git: Commit All command. Write a brief, descriptive commit message when prompted.

Next, you’ll want to ensure that your changes don’t have conflicts with the current state of the Popcode code base—including any updates that were made while you were working on your project. To do this, use the Git: Pull From… command again, choosing upstream and upstream/master. If there are any conflicts, you can resolve them using VS Code’s built in tools.

If you had any merge conflicts, it’s a good idea to manually test your changes using your local Popcode instance one last time, to make sure that the conflict resolution didn’t introduce any bugs.

Finally, run the task Popcode: Run All Tests and Checks. This will run the same Jest and Karma tests that you have been running in watch mode, but will additionally perform a few other checks that are run during continuous integration. This will give you early warning of any problems that otherwise wouldn’t pop up until CI completed on your pull request.

Creating a pull request

Now it’s time to create a pull request, which makes your changes available to the Popcode maintainers, giving them the ability to review them, give feedback, and ultimately merge them into the official codebase.

To create a pull request, run the GitHub Pull Requests: Create Draft Pull Request command. When prompted for the remote, be sure to choose popcodeorg:popcode, and for the target branch keep the default of master. At the next prompt, the remote to publish your branch to, choose the option corresponding to your fork of Popcode. For the last prompt, for the name of the upstream branch, you can keep the default, which should be the name of the branch you’ve been working on locally.

This will open a pull request tab in your editor. Where you see the No description provided placeholder, click the pencil icon in the top-right corner to enter edit mode, and write a description of your changes. This description should include a high-level summary of the new feature/enhancement/bugfix; why this change was worth making (if it’s not obvious); and a discussion of any noteworthy technical decisions that went into your implementation. If your pull request is directly addressing an issue, then on the last line of the description, write Closes # followed by the issue number; e.g. if you are addressing Issue 1234, write Closes #1234.

Update the title, if necessary, to concisely describe the change you’ve made.

Next, click the + next to Reviewers, and select outoftime; this is Mat, Popcode’s maintainer.

Finally, click the Ready for review button to submit the pull request for review.

Finishing your pull request

Opening your pull request will automatically kick off the continuous integration process, which runs a comprehensive set of tests and checks on the code base to catch potential problems. If you ran the Run All Tests and Checks command as recommended above, CI should bring no unpleasant surprises.

All pull requests are also reviewed by a human, typically Mat, Popcode’s maintainer. This code review can generate feedback on everything from potential bugs, to structural decisions about the code, to clarity and idiom, to keeping code style consistent. You’ll get an email from GitHub when your pull request is reviewed; usually this should happen within a day or two.

After one or more rounds of feedback, your pull request will be approved, and typically will be immediately merged into Popcode’s official codebase. Merging the pull request automatically kicks off a release process; your code should be live about 20 minutes later!