From 2aeebcda5ac96d4c0fba77e4b0ed8b068640d71a Mon Sep 17 00:00:00 2001 From: Molly Struve Date: Thu, 11 Jun 2020 17:50:32 -0500 Subject: [PATCH] Documentation: Add More Knapsack Information to Docs (#8419) Co-authored-by: Mac Siri Co-authored-by: Vaidehi Joshi --- README.md | 4 +++- docs/deployment.md | 46 +++++++++++++++++++++++++++++++------------- docs/tests/readme.md | 18 +++++++++++++---- 3 files changed, 50 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index af24c8a3f..457aa1ce4 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,9 @@ Honeybadger badge + + Knapsack Pro Parallel CI builds for dev.to +

Welcome to the [dev.to](https://dev.to) codebase. We are so excited to have you. @@ -113,7 +116,6 @@ A more complete overview of our stack is available in - [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) - ### Installation Documentation [View Full Installation Documentation](https://docs.dev.to/installation/). diff --git a/docs/deployment.md b/docs/deployment.md index 0183c1c06..6faea7514 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -12,23 +12,43 @@ deployed to production once the build steps complete successfully. The process currently takes about 20 minutes to complete and will need a few additional minutes before the change goes live. -## Travis steps +## Travis Stages -The following steps can be explored in our +The following stages can be explored in our [.travis.yml](https://github.com/thepracticaldev/dev.to/blob/master/.travis.yml) and [Procfile](https://github.com/thepracticaldev/dev.to/blob/master/Procfile). -Some of the steps will be parallelized in the future: +Our Travis CI process consists of 2 stages. -1. Travis runs the test portion of Rails code. -1. Travis runs the test portion of Preact code. -1. CodeClimate-test-reporter combines the test result and coverage from Ruby and - JavaScript code then uploads it to our CodeClimate dashboard. -1. `bundle-audit` checks for any known vulnerability. -1. Travis builds Storybook to ensure its integrity. -1. Travis deploys code to Heroku. - - Heroku runs the database migrations and Elasticsearch updates before - deployment. -1. Travis notifies the team that the process completed. +1. Running our test suite in 3 parallel jobs. +2. Deploying the application if we have merged with the master branch and the + `[deploy]` flag is present in the merge commit. + +### Stage 1: Running Tests + +In stage 1, we use [KnapsackPro](https://knapsackpro.com/) to divide our Rspec +tests evenly between 3 different jobs (virtual machines). This ensures that each +job takes relatively the same amount of time to run. After running our Rspec +tests, we then run a series of other checks. These additional checks are split +up between the different jobs. Here is a list of those additional checks that +are run. + +- Job 0 is where we run Javascript tests, Preact tests, and coverage checks. +- Job 1 is where Travis builds Storybook to ensure its integrity, and where we check for any known vulnerabilities using `bundle-audit`. +- Job 2 is where Travis fires up a Rails console to ensure the application loads properly, and where specs with KnapsackPro are run. + +If all of the jobs pass then we move on to Stage 2 of the Travis CI process. + +### Stage 2: Deploying + +If the build was kicked off from a pull request being created or updated this +stage will do nothing. If the branch has been merged into master with the +`[deploy]` flag, then this stage will kick off a deploy. The deploy will run in +its own job deploying our application to Heroku. + +Prior to deploying the code, Heroku will run database migrations, Elasticsearch +updates, and do some final checks (more information on that below) to make sure +everything is working as expected. If these all succeed, then the deploy +completes and our team is notified. ## Deploying to Heroku diff --git a/docs/tests/readme.md b/docs/tests/readme.md index 377c49e9c..0c18e113d 100644 --- a/docs/tests/readme.md +++ b/docs/tests/readme.md @@ -46,9 +46,13 @@ about We are using Travis for CI and CD. Travis will run a build (in an isolated environment for testing) for every push to this repository. We also recently added [KnapsackPro](https://knapsackpro.com/) to our Travis CI setup. -KnapsackPro allows us to split up our tests evenly between 3 different virtual -machines. These 3 virtual machines all run in parallel which helps decrease the -time needed to run all of our specs. +KnapsackPro allows us to split up our tests evenly between 3 different +jobs(virtual machines). These 3 jobs all run in parallel which helps decrease +the time needed to run all of our specs. + +If you want more information about your CI job or how long specific specs take +to run you can find all of that information on our +[KnapsackPro public dashboard](https://knapsackpro.com/dashboard/organizations/1142/projects/1022/test_suites/1434/builds). Keep in mind that a passing build does not necessarily mean the project won't run into any issues. Strive to write good tests for the code you wish to @@ -57,7 +61,13 @@ contribute. Travis will deploy your pull request to production after CI passes and a member of the DEV team has approved it. -Our test suite is not perfect and sometimes a re-run is needed. +Our test suite is not perfect and sometimes a re-run is needed. If you encounter +a "flaky spec" that fails intermittently please open an issue so we can address +it. In order to get your test suite to pass after a flaky spec has failed simply +retry the individual job that failed rather than the entire suite in order to +save some time. When you retry the individual job, make sure to also retry the +Deploy job. Even though you may not be deploying that job must complete for the +entire build to pass. Please note that you will need to have Elasticsearch installed and running for certain tests in our test suite. You can find instructions on how to install and