Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Quick Start docs #296

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Update Quick Start docs #296

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
6053b6c
First draft of ruby instructions
jamesnaftel Apr 22, 2021
da78f3d
link from main README.md to Ruby
jamesnaftel Apr 22, 2021
4f8a1a2
updated based on Ross' comments and added observation mode
jamesnaftel Apr 29, 2021
0fd4892
add link to pypi docs
jamesnaftel May 3, 2021
c67d762
Added Christina's PR feedback.
jamesnaftel May 12, 2021
6320aee
fixed formatting and added support email
jamesnaftel May 12, 2021
4542623
Update docs/yourbase-ruby.md
jamesnaftel May 20, 2021
0174eac
updated based on PR comments
jamesnaftel May 20, 2021
10dd863
clarity and naming improvements
jamesnaftel May 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,7 @@
- [Package Configuration Reference](configuration.md)
- [CI Acceleration and Caching](ci-caching.md)
- [Design Philosophy](design-philosophy.md)

# Quick Start Acceleration
clausti marked this conversation as resolved.
Show resolved Hide resolved

- [YourBase Ruby Acceleration](yourbase-ruby.md)
59 changes: 59 additions & 0 deletions docs/yourbase-ruby.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# YourBase Ruby Acceleration

Tests are important. For large monoliths, they're also a major source of drag on velocity.

YourBase is a tool that traces your tests to determine which functions each test depends on. It can later use this information to determine which tests do not need to run because their code paths have not changed. These tests are skipped automatically.
clausti marked this conversation as resolved.
Show resolved Hide resolved

YourBase works with Ruby versions >= 2.3
clausti marked this conversation as resolved.
Show resolved Hide resolved

## Getting Started
No configuration, setup, or babysitting required. To get started, you need the YourBase gem and a download token. To request a token, please visit [YourBase.io](https://yourbase.io/download)
clausti marked this conversation as resolved.
Show resolved Hide resolved

Once you have a token, simply follow the steps below:
```sh
YOURBASE_DOWNLOAD_TOKEN=<enter token>
bundle add yourbase-rspec --git "https://$YOURBASE_DOWNLOAD_TOKEN:[email protected]/yourbase/yourbase-rspec-skipper-engine.git"

bundle install
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recommend following the advice in https://www.vidarholen.net/contents/blog/?p=958:

Suggested change
YOURBASE_DOWNLOAD_TOKEN=<enter token>
bundle add yourbase-rspec --git "https://$YOURBASE_DOWNLOAD_TOKEN:x-oauth-basic@github.com/yourbase/yourbase-rspec-skipper-engine.git"
bundle install
bundle add yourbase-rspec --git "https://${YOURBASE_DOWNLOAD_TOKEN?}:x-oauth-basic@github.com/yourbase/yourbase-rspec-skipper-engine.git" &&
bundle install

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this! Very clear.

```

## First run
After installing yourbase-rspec, if you are not using Rails you must add
"require 'yourbase-rspec'" in your spec folder.
clausti marked this conversation as resolved.
Show resolved Hide resolved

```sh
# Add require for non Rails projects
echo "require 'yourbase-rspec'" >> spec/yourbase_spec.rb
jamesnaftel marked this conversation as resolved.
Show resolved Hide resolved
```

Run your tests with the same command you typically use. You should see a rocket ship at the beginning the RSpec test section.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Run your tests with the same command you typically use. You should see a rocket ship at the beginning the RSpec test section.
Run your specs as you normally do-- `yourbase-rspec` is compatible with any `rspec` command line options. You will see a rocket ship at the top of the `rspec` output if `yourbase-rspec` is successfully running! 🚀

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you would not like to take the change verbatim, can you update the text to include the information about compatibility with command line arguments and the literal emoji? It's not clear to me that everyone (especially devs with a different native language) will automatically know "rocketship" means "🚀"


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should have a section about Spring here, because it's the most common reason they won't see the rocketship.

Right now, they need to run spring stop from the command line to turn it off, but it would be better if we could figure out if manually requiring yourbase-rspec at the top of the spec_helper.rb gets around the incompatibility, so that we could tell them to do that instead of having to stop Spring. Stopping Spring is definitely fine in the CI but is a little kludgier for local dev where Spring does actual useful things, including shorten the spin-up time for "loading the rails environment" for specs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. Have this in my notes but wanted to try it out first. Will add it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think for now it is sufficient to say that if you do not see the rocketship but ARE running Spring, that it should be turned off to accelerate the tests.

```
🚀
```

The first run will be cold, so if you just want to see YourBase in action and your tests are going to take a while, you can run a subset of tests. Tracing data for the subset will be used correctly even if you later run all tests.
clausti marked this conversation as resolved.
Show resolved Hide resolved

After the run finishes, running again will skip all tests. Modifying a dependency will run only tests whose code paths touched the changed code. You're YourBased! 🚀

## RSpec Output

YourBase enhances the output so that you can clearly see the results of the Gem.
clausti marked this conversation as resolved.
Show resolved Hide resolved

For an accelerated run, you will see the number of skipped tested added to your
RSpec summary line:
```sh
clausti marked this conversation as resolved.
Show resolved Hide resolved
1 examples, 0 failures, 1 skipped with YourBase🚀
```

To get additional details, please use -f, --formatter [p]rogress | [d]ocumentation]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like it's supposed to include a documentation link?


## Cohorting / Sharding
clausti marked this conversation as resolved.
Show resolved Hide resolved
YourBase supports sharding your tests without negatively affecting tracing or acceleration. It uses consistent hashing to split tests into cohorts that stay the same between runs, even as the test pool grows or shrinks.

1) Set YB_COHORT_COUNT to the number of cohorts your tests should be split into. This should be the same among all shards.
1) Set YB_TEST_COHORT to the cohort ID this run should identify as, starting with 1. This should be different among all shards.
Without these set, YourBase assumes a value of "1" for both, meaning one shard will run one cohort; that cohort will contain all tests.

Note that tests are only guaranteed to remain in the same cohort as long as
YB_COHORT_COUNT doesn't change.
clausti marked this conversation as resolved.
Show resolved Hide resolved