Overview

Review 101

Video training content goes stale. egghead.io should be as up to date as possible when it comes to content. Because of the nature of video we need to monitor each lesson on multiple levels.


Lesson Video

An excellent coding screencast will focus on core concepts and have the ability to remain “evergreen” through minor revisions of the library that it is demonstrating. We need to continue to monitor this to make sure that it is the case.

When differences exist we can take several courses of action:

  • update the code sample and use comments in the code to notify the user that it has changed from the video
  • Annotate the lesson’s page to tell the student what is wrong with the lesson
  • Replace the lesson video/code with an updated version
  • mark the lesson as obsolete/deprecated
  • record a new version (vs replacement)

Update Lesson Code Sample

This is the most common action taken by the reviewer. The lesson code sample should reflect the current version(s) for the libraries it is demonstrating (libraries are updated often!). The sample code can correct for minor differences in the code demonstrated in the lesson video, noting with comments when this has been done.

Annotate the lesson page

When there is some significant breaking difference in the lesson video and code sample, we can create a notification to be displayed prominently on the lesson page. This notification comes in the form of an errata which is shown below:

Errata Example

Replace the lesson video/code

If the lesson still has significant value conceptually, we can re-record the lesson and produce an updated code sample. We want to do this for popular lessons and maintain our SEO.

Make a note of why you think the lesson needs to be re-recorded in the review document.

Mark as obsolete

Like Annotation above, but more deadly! :skull:

Record a new lesson

Sometimes we will want to record a new lesson that presents the underlying concept with the updated version instead of replacing it in-place

Setup

There are a few essentials needed on your computer in order to review. In this section you are going to follow along and install everything that is needed.

Quick Install (Mac)

Open up your terminal paste in the following and then press return to install Homebrew: /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Afterwards you're going to run each of the following in your terminal:

  • Google Chrome: brew cask google-chrome
  • Slack: brew cask install slack
  • GitKraken: brew cask install gitkraken
  • Visual Studio Code: brew cask install visual-studio-code
  • Yarn: brew install yarn

Google Chrome Plugins

React Developer Tools

The React Developer Tools extension is needed for reviewing our React course content. You can install it here: React Developer Tools

Video Speed Controller

Video Speed Controller allows you to quickly adjust the video speed with your keyboard. Install it here: Video Speed Controller

VS Code Extensions

Extensions enable VSCode to be more helpful, providing more visual feedback or shortcuts that prevent you from having to type more than necissary.

You can install these extensions by running the provided scripts from your terminal.

Markdown All in One

Markdown All in One provides you with shortcuts and a preview of your markdown.

Install script: code —-install-extension yzhang.markdown-all-in-one

ESLint

ESLint warns you if you are breaking any rules inside your editor, letting you know if you've made a mistake early.

Install script: code —-install-extension dbaeumer.vscode-eslint

Prettier

Prettier formats your code when you save a file, ensuring that all outputted code conforms to a consistent style.

Install script: code —-install-extension esbenp.prettier-vscode

Quokka.js

Quokka.js is a rapid prototyping playground for JavaScript and TypeScript. It runs your code immediately as you type and displays various execution results in your code editor.

Install script: code —-install-extension wallabyjs.quokka-vscode

Github Pull Requests

This lets you view and create pull requests inside the editor!

Install script: code —-install-extension github.vscode-pull-request-github

Accounts

Github

Your Github account is what you'll use to create accounts with all the other required services.

Sign up here 👉 github.com

Once you have an account created contact a Content Team Lead and they will provide you with the invitations to egghead.io's Github organizations.

Required Learning

Learning Git

Git is the standard tool used by teams to all work on the same project together. It allows everyone to make copies of the original project, make changes to their copies, and then merge their changes into the original without getting in the way of anyone else's work.

Git Terminology

Git has some fancy jargon that everyone uses, but what does it all mean and how does it connect? Let's break it down into layman's terms! 👨‍🏫

Change

Git keeps track of all of the files in a project. Whenever you make a change to a file, git knows precisely what you've changed and keeps track of it.

Commit

A commit is a collection of changes. Whenever you make a commit you are telling git that you'd like it to save all of the changes that you've made.

Branch

A branch is just a sequence of commits, so all of the changes you've made starting from the beginning of the project.

Whenever you branch you split off from the commit you are at currently. Other branches don't keep track of the commits you make on a separate branch, this allows you to make changes without stepping on anyone else's toes!

Repository

A repository, also known as a repo, is a collection of branches. It is the entire project, every commit on every branch.

Remote

A remote is a repository that isn't the one you are in currently. You can link to a remote to push and pull from it.

Push

When you push, you upload your commits from a branch on your computer to a remote repository's branch

Pull

When you pull, you download the commits from a remote repository's branch to a repository on your computer's branch.

Merge

Merging is when you synchronize the commits of two branches.

In a collaborative project, when someone wants to make a change, they make a branch off of a main branch known as the master branch. After they commit changes they've made to their branch, they would merge their commits into the master branch.

A merge conflict is when two commits change the same thing!

🐙 GitHub

GitHub is a website that hosts remote repositories!

Clone

A clone is a copy of a remote repository. If you don't have permissions, you cannot push changes to the remote.

Fork

A fork is a clone of a repository on Github under your name. You can push changes to your forked repository!

So how do you use git?

There are a couple of options. You can either use a GUI, which is an app that provides a visual interface, or you can use your command line and run the commands yourself.

The GUI that we recommend that you use is Git Kraken. Git Kraken provides an excellent diagram of all of the branches and changes, and it makes cloning projects and committing your work much easier.

gitkraken

How do you use Git Kraken?

Git Kraken has an excellent tutorial on how to use the product, I highly recommend you read this article and watch the videos. https://support.gitkraken.com/start-here/guide/

How do you use Git from the command line?

This tutorial from code academy will take you through the workflow basics, how to undo any mistakes you make, branching, and collaborating with other people

Taking it Further

If you'd like to learn git a bit more in depth, egghead.io has the course Practical Git for Everyday Professional Use!

Communication and Work Structure

Overview

There are quite a few tools that we use at egghead that allow us to communicate, organize, and plan our thoughts and work. This section will explain how we use each tool and give you an understanding of why we use it.

After reading this section, you'll know how we communicate as a team at egghead and where work is done.

We'll cover:

  • Github
  • Slack
  • Email
  • Topic Box

GitHub

GitHub is a website and service used to store and track the development of software. It does this through Git which the tool that actually keeps track and manages code.

GitHub is a hosting service for projects (repositories) that use Git. It's not the only service that does this but is widely accepted, especially in Web Development.

For more specifics on Git, visit our Prerequisite section [link to that].

GitHub & the Review Team

GitHub is where we store code examples for the content that is created at egghead. Specifically, all code is stored under the eggheadio-projects organization.

Each repository (with a few exceptions) in this organization will correlate to a course that has been or will be published on egghead.

Github Projects

Work is assigned through GitHub Projects which can be found here.

You can navigate to the project from the organization home page here:

screenshot of github projects button

Then select Review Team Projects

This will bring you to all the current reviews that are currently being worked on as well as available for review.

screenshot of github projects button

On this board we have 4 columns: Todo, Working On, Needs Review, and Dependency Data Merged.

When a course is flagged for review, it will be added to the Todo column as an issue by a Review Team Admin. When you are ready for a new project, you can assign yourself to the issue and drag the issue to the Working On Column.

When a review is done, you will need to move the related issue to the Needs Review column for review by a Review Team Admin. In addition you'll need to post to Slack (covered in next section).

When the review is approved, the issue will be closed and moved to the Dependency Data Merged column.

Review Project Issue

screenshot of github projects with issue open

This will take you to the full issue page that will describe for you what needs to be done and give appropriate links for you to start the project.

screenshot of github projects button

Each card will have the lesson minutes and pay at the top of the card as well as quick references for Setup, The Review, Finished, and Copying the JSON (We'll cover more specifics in the review section).

In addition, more context will be added to the top of the card when available. Notes on previous pain points in past reviews, comments from customers, relevant changelog notes of a specific technology, etc.

Asynchronous Communication

Because team members are spread across the globe, our primary form of communication is asynchronous. We use Slack as the day to day tool for questions that need to be answered immediately as well as a place to post work, ask for reviews

  • email

Review 101

Review Process Steps

Video training content goes stale. egghead.io should be as up to date as possible when it comes to content. Because of the nature of video we need to monitor each lesson on multiple levels.

This document will detail what you need to know to get started with a review as well as context for what to do to when you find stale content.


Lesson Video

An excellent coding screencast will focus on core concepts and have the ability to remain “evergreen” through minor revisions of the library that it is demonstrating. We need to continue to monitor this to make sure that it is the case.

When differences exist we can take several courses of action:

  • Update the code sample and use comments in the code to notify the user that it has changed from the video
  • Annotate the lesson’s page to tell the student what is wrong with the lesson
  • Replace the lesson video/code with an updated version
  • Mark the lesson as obsolete/deprecated
  • Record a new version (vs replacement)

Update Lesson Code Sample

This is the most common action taken by the reviewer. The lesson code sample should reflect the current version(s) for the libraries it is demonstrating (libraries are updated often!). The sample code can correct for minor differences in the code demonstrated in the lesson video, noting with comments when this has been done.

As most of the actions you will take relate to code, the following steps detail the processes that egghead reviewers (you!) take to handle discrepencies with dependency versions and subsequent breaking changes within code.

Branch flow going from work to Pull Request to merged

Glossary

  • Repo - source code on Github called a repository.
  • Issue - conversation in a repo before proposing changes.
  • PR - special issue attached to proposed changes called a pull request.
  • Code review - PR approval process with conversations attached to specific lines of code.
  • Project board - the eggheadio-projects GitHub organization's project board.

Steps

Anyone (e.g. end users or Greenkeeper)

We want everyone to report issues, not just admin! Issues are reported from users in serveral different channels which include: Twitter, HelpScout (our customer support software), Slack (flagged in #egghead-support and #content-team), and eggheadio lesson comments.

This can be tough to all keep track of. If you notice a user having an issue with a code behavior, open an issue in the repo and link it in #content-team.

  1. Create an issue in a repo.
  2. Add to the Review Team Projects project board
  3. GitHub automatically adds the issue to the To do column on the project board.

Reviewer

All courses that need review will be added to the Review Team Projects project board in the To do column. The following steps detail what you need to do to claim and finish a review:

  1. Pick an issue from the To do column on the project board.
  2. Manually move the issue to the In progress column on the project board.
  3. Assign yourself to the issue.
  4. Fork the repo.
  5. Commit updated dependencies and lock file.
  6. Commit changes to resolve the issue.
  7. Commit updated changelog.
  8. Close the issue in a commit message.
  9. Create a PR and allow changes to your PR’s branch.
  10. GitHub automatically adds the PR (not the issue) to the Code review column on the project board.
  11. Commit changes requested in the code review.

Continuous Integration TODO: Milestone 1

  1. Lint changelog.
  2. Check install for errors.
  3. Check build for errors.
  4. Check tests for errors.

Admin

These actions are taken by Review Team leads when you are finished with a review. When you PR code, this is where the team will discuss questions and issues that are surfaced through your review that need more conversation.

  1. Request changes in the code review.
  2. Check out the PR in official VS Code extension.
  3. Commit updated lock file to the PR’s branch if it was updated in CodeSandbox.
  4. Approve the PR.
  5. Merge the PR.
  6. GitHub automatically moves the PR to the Resolved column on the project board.
  7. GitHub automatically closes the issue and moves it to the Done column on the project board.
  8. Manually move the PR to the Done column on the project board when deployed.

Web Service TODO: Milestone 2

  1. Receive [pull_request](https://developer.github.com/v3/activity/events/types/#pullrequestevent) event from GitHub webhook.
  2. Process changelog.
  3. Update database.

Updating Dependencies

Run yarn latest, A, Return in the workspace root. Currently, it aliases yarn upgrade-interactive --latest && yarn upgrade -L.

Changelog Format

egghead uses the Changelog to document reviews in a consistent, machine-parseable format that details the version changes between reviews. When discrepencies between versions happen (they will), what is added, removed, changed, deprecated,and fixed is logged to provide information about the current state of the project.

Install the VS Code extension.

This template should be added to a repository if one does not already exist:

Template

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

### Changed

### Deprecated

### Removed

### Fixed

### Security

## 1.0.0 - YYYY-MM-DD

### Added

- This file.

Other Actions

When simply updating the code is not enough, there are a few more options available to us to inform users of breaking changes that might have occured.

These are some common actions that are suggested by a reviewer during the Pull Request process for larger issues that need more attention.

Annotate the lesson page

When there is some significant breaking difference in the lesson video and code sample, we can create a notification to be displayed prominently on the lesson page. This notification comes in the form of an errata which is shown below:

Errata Example

Replace the lesson video/code

If the lesson still has significant value conceptually, we can re-record the lesson and produce an updated code sample. We want to do this for popular lessons and maintain our SEO.

Make a note of why you think the lesson needs to be re-recorded in the Changelog.

Mark as obsolete

Like Annotation above, but more deadly! :skull:

Record a new lesson

Sometimes we will want to record a new lesson that presents the underlying concept with the updated version instead of replacing it in-place.

The Review Process

Identify Change(s) in a Framework

Project Structure

JavaScript frameworks are continually changing and updating. A lot of the time this is not an issue for our lessons.

JavaSript projects keep track of changes through a package.json that can be found in the root of the project. The package.json file contains the meta-data for the project like the authors' name, a scripts section, dependencies section, and devDependencies section.

The dependencies section contains the list of all the libraries used in the project that are essential for the application to run (e.g., React, Angular, Redux, RxJS).

{
  "name": "redux-course",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "json-server": "^0.13.0",
    "react": "^16.4.0",
    "react-dom": "^16.4.0",
    "react-redux": "^5.0.5",
    "react-router-dom": "^4.1.1",
    "redux": "^4.0.0",
    "redux-devtools-extension": "^2.13.2",
    "redux-thunk": "^2.2.0",
    "yarn": "^1.6.0"
  },
  "devDependencies": {
    "react-scripts": "1.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "production": "json-server --static ./build db.json",
    "build": "react-scripts build",
    "test": "react-scripts test --env=jsdom",
    "eject": "react-scripts eject",
    "dev-server": "json-server -p 8080 db.json"
  }
}

Each of these dependencies has a version number listed that informs npm (or Yarn) to download the version specified.

The version number follows the Semantic Versioning Specification (SemVer).

Semantic Versioning (SemVer)

SemVer attempts to provide more meaning of the underlying changes in a project through additional structure to version numbers.

Each Version X.Y.Z must be non-negative numbers starting and (supposed to) have non-leading zeroes (though many libraries start at 0.1.0).

  • X is a MAJOR version

  • Y is a MINOR version

  • Z is a PATCH version

With these versions specified, 0.2.10 is ordered before 0.3.1 and subsequently, 1.0.0 comes after both 0.2.10 and 0.3.1.

A PATCH version is incremented when internal bugs are fixed in a library that does not affect any projects. MINOR versions are incremented when there is 'backward compatible' features introduced to a library or significant improvements to the internal workings of the library are added. MAJOR versions are incremented when there are Breaking Changes introduced to the library.

In the previously mentioned example, theoretically, there are backward compatible features added in-between the packages 0.2.10 and 0.3.1 versions. When the package reached 1.0.0, it can be assumed that it contains breaking changes if you wrote your application on a previous version (e.g., 0.2.10 or 0.3.1).

SemVer Version Ranges

A lot of the time, specifying a single version of a technology is too fine grain and restrictive because subsequent MINOR and PATCH updates won't break the project that the dependency is in. It can be annoying to have to update version numbers every time a MINOR or PATCH version is released.

This is why SemVer has version ranges which can be denoted a few different ways. The simplest ways are to use a set of primitive operators, which are: < Less than, <= Less than or equal to, > Greater than, >= Greater than or equal to, and = Equal. = can be assumed when no operator is present.

For review, a range specifying >15.3.0 <16.4.1 says the course started at version 15.3.0 and is valid up to all version (excluding) 16.4.1 where a <=16.4.1 will specify the version including 16.4.1.

Simply putting 15 - 16 is another way to specify a range that will encompass all MINOR and PATCH versions contained within the MAJOR versions 15 and 16. This is preferred as it is the most flexible way to specify a version range. If more specifics are required, other operators can be used.

To make versions easier to specify, the squiggly ~ and caret ^ also identify ranges. When ~ is placed before version (e.g., ~15.0.0), it specifies all versions incremented at the PATCH level. In other words 15.0.1, 15.0.3, or 15.0.19 are all valid. In other words, ~15.0.0 equals >=15.0.0 <15.1.0.

The caret ^ specifies all version increments at the MINOR and PATCH levels. ^15.0.0 specifies that any of these following versions are valid: 15.0.1, 15.1.3, or 15.5.0. in other words, ^15.0.0 would equal the range >=15.0.0 <16.0.0.

A great place to explore semantic versioning is the npm SemVer calculator

Pre-release Versions

Many projects will have several pre-release versions published before an official version is published. These pre-release versions are subject to change and can be typically ignored when updating lesson code.

Pre-release tags range from alpha, beta, and rc (release candidate). With the specified order as follows: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

It is good to note that a pre-release is available and what stage they are in as that likely means a MAJOR version update is close to being published and will trigger more reviews.

Review with SemVer Versions in Mind

You need to identify these Breaking Changes​​​​​​​ and keep them in mind when watching through lessons.

Each framework or library will have a CHANGELOG.md that will record the changes of that specific framework. (link to example) Usually found on the respective frameworks github page.

Most frameworks use Semantic Versioning (SemVer) to keep track of updates. We are mostly interested in Major and Minor

Under each new version, there will be a Breaking Changes (or similarly named) section that is where you will see what exactly will break any lesson examples that egghead might have.

Track Course Dependency Information

egghead is now keeping track of all the relevant dependency versions related to a course

i.e., A course on "State Management with Mobx in React" will track the version range that starts with the course published version and ends with the current version the course example.

Data for this looks like:

{
        slug: 'manage-complex-state-in-react-apps-with-mobx',
        dependencies: {
          mobx: '2 - 5',
          react: '15 - 16',
        },
        reviews: [
          {
            performedOn: '2018-07-17',
            performedBy: 248653,
            scopeOfReview: 'full course lesson review',
            notes: [
              {
                type: 'major issue',
                title: 'removed line- “useStrict(true);',
                details: 'The useStrict terminology is no longer recognized',
              },
              {
                type: 'major issue',
                title: 'Keys and values now return iterators',
                details:
                  'keys and values now return iterators, to return an array, use Array.from with the iterator https://github.com/mobxjs/mobx/issues/1488',
              },
            ],
          },
        ],
      },

As seen above, every review is recorded with the date it was done (in YYYY-MM-DD format), the scope, and most importantly, any notes or issues that came up during the review.

The range specifies the range that starts with package versions that the course was released on and ends with the latest version the course was updated to. For the example specified above, the course was released with React v15 and has since been updated to React v16. The specific MINOR and PATCH versions aren't necessary to specify here because there are no major breaking changes of concern apart from the notes provided.

Title a egghead.io lesson

[How Do I…] Standard

The title of the video needs to reflect the question that is answered in the video. Finishing the How do I… question is a great way to accomplish this and is the standard for our lessons.

This is a standard that we have adopted recently so many of our older lessons and courses do not have this standard applied and need to be updated accordingly.

Another way to think about the title of a video is that it is the summary of the description (of the video). If the summary answers the question the title proposes, you are on the right track.

90 character limit

Search Engine Optimization (SEO)

Our titles are also one of the main resources we use for exposing our content to the internet. We want to include the technology that the lesson is covering in the title.

Here's a list of lesson title examples and how we updated the titles to our new standard.

Old Title

  • Filters
  • Observables are almost like Functions
  • Creation operator: of()
  • Understand Elm’s Bool Type

Updated Title

  • Filter Input in AngularJS
  • Return Multiple Values with Observables in RxJS
  • Deliver Synchronous Values with the RxJS of() Operator
  • Pattern Match Expressions with Elm’s Boolean Type

Your course code example

A course typically has one code example that acts as a connecting thread through the course. You’ll build on it from lesson to lesson.

For every egghead lesson, we provide a concise, organized, readable code example below the lesson video in a runnable embed, using CodeSandbox or a similar service. That way, egghead members can jump in right away.

The structure that has worked best is to place each lesson example in it's own folder on the master branch numbered acording to the lesson order in the course. This allows for quick access to each lesson without the hassle of switching branches (this is important for further maintanence!).

Here's an example of the structure that we expect:

screenshot of code example on github

Each folder contains a create-react-app application that's ready to run.

screenshot of specific folder of code example on github

How Code is Shared

For each lesson in a course, a code example is provided in its finished state below the video so learners can explore the code on their own.

CodeSandbox is our favorite tool for creating and delivering our examples. If this won’t work for the code, we use a GitHub repository to store the code example and share that on the lesson page. GitHub repo examples will be structured in the same way, where each folder is the finished state of the given lesson.

Poviding a app.start.js file (or folder if a few files in one lesson are touched) is a great way to encourage students to code the lesson themselves.

Enhnacements to the Code Example

To further the useability of each repository, egghead will implement Yarn Workspaces which allow anyone to yarn install once for the entire repository and each lesson will be ready to run. No more hassle for the student to install in every lesson folder.

This is opt in for each student as she can still navigate to the lesson folder and npm or yarn install, but for maintanence purposes, workspaces greatly increase the speed of updating and ensuring every lesson is running as it should.

Two additional requirements for each lesson folder are a unique name in it's respective package.json file as well as version set.

As seen here in this example:

screenshot of lessons package.json

Next, all lesson folders (or workspaces) are aggregated in a packages folder and a global package.json file is created to enable the workspaces.

screenshot of lessons package.json

Within that package.json file, you'll set workspaces to packages/* and private to true. Now you're all set up with what you need to run each example as a workspace.

You'll notice that we've added a few handy scripts in this global package.json that allow you to easily run and update each lesson.

yarn start 01

💥 The first lesson is ran.

Review Template

Install the VS Code extension.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

Changed

Deprecated

Removed

Fixed

Security

1.0.0 - YYYY-MM-DD

The Code Part

  1. What to ask
  2. Debugging
    1. know when to stop and ask for help
  3. Updating
  4. Migration
    1. Services (codesandbox, local server, plunkr, etc.)
    2. Changing a project's structure

Getting Paid

  1. introduction with deborah
  2. routing number
  3. account number
  4. Wave? - creates invoices, receipts