Cue-to-Cue Dry Run of the Agile Workflow
In theater, a "cue-to-cue" rehearsal is one in which (roughly) only the first and last lines of dialogue in each scene are spoken, because the point of the rehearsal is to practice the technical "cues" that occur between the scenes, such as lighting changes, sound effects, moving props around on stage, and so on. In other words, the rehearsal is about everything except saying the actual dialogue lines.
Similarly, in this assignment you'll practice the tool-rich Agile/XP workflow by doing everything except writing code and tests (except in the most trivial sense), to practice getting into the rhythm of the various tools used in the workflow.
In addition to the usual tools used in this course, we're also using an experimental tool, Bluejay, that helps you keep track of whether you're following Agile best practices across tools, such as whether claiming a story on Pivotal Tracker is closely followed by creating a feature branch for that story.
This assignment is intended to be done with your team using a single shared repo. Many of the steps can be done in parallel; we suggest reading through the whole thing first and determining when pairs can work in parallel on different steps. Being in constant contact with your team for coordination will help.
|Warning. This is a mostly step-by-step process, but it is not a mindless cookbook recipe. You will have to look up additional information and "fill in some blanks" as you go. Similarly, when we direct you to documentation for setting up external tools, and that documentation includes examples files, do not mindlessly copy and paste the files; take the time to understand what each step is actually supposed to accomplish and what parts of the "recipe" must be adjusted for your specific app. Use the Google. Use the Force. Use whatever works for you. But don't assume that 100% of the keystrokes you need to type are given here, and remember when you run into trouble, Read the error message, Ask your teammates or colleagues a well-formed and well-informed question, Search the interwebs for relevant info, and if necessary Post on the course forums or StackOverflow.
Create the app & repo
One person or pair should do these steps:
Be sure you have a recent version of Ruby, >= 2.6.6. (Earlier 2.6.x versions have bugs.) You should already have
rvm set up from the previous assignment;
rvm use 2.6.6 (or a later version of Ruby) before proceeding!
rails -v to ensure you’re running the desired version of Rails. If not, run
gem install rails -v x.x.x with x.x.x set to the version you want; 4.2.9 for example.
rails new appname
--skip-spring --skip-turbolinks --skip-test --skip-webpack-install to create the new app. (We recommend omitting the Spring app runner, Turbolinks nonsense, and
Test::Unit testing framework, respectively, and only installing Webpack support if you are pretty sure you'll need it, since it also requires Yarn and Node to be installed separately. Note: if you skip Webpack, which we recommend, you must also remove the
webpacker gem from the Gemfile and re-run Bundle, and you must delete the call to
config/webpacker.yml if it's present (it shouldn't be unless you tried to start the app before removing the Webpacker gem).
cd appname to navigate into your new app’s root directory. From now on, all shell commands should be issued from this directory.
Check: Make sure your app runs by executing
rails serverand visiting the app’s root URI. You should see the Rails welcome page.
- So far so good. But the app will not actually work in deployment on Heroku unless there is an explicit route for the home page, "/". Add a route for the home page, and a single controller and view for that route. The view should just display the name of one of your team members, chosen at random; you'll add more later. Check: running the app locally and going to its home page now serves that view.
The Rails app creation command automatically sets up your app’s root directory as a GitHub repo. Add the files associated with your app, making sure to exclude
tmp. (A good exercise: do this by adding those paths to
.gitignore, which should itself get added to the repo.)
Create a GitHub repo via GitHub’s web interface, and do the initial commit and push of your new app’s repo. Give your team push access on the repo. Have every team member clone the repo to their local environment. Warning: depending on which version of Rails and your local settings, the default branch of your local repo may be named either
main. Before pushing, make sure the default branch of the GitHub-created repo has the same name!
Create a Tracker project
- Use a free Pivotal Tracker account to create a project for this assignment, and add all your teammates to it. (The free accounts allow only 5 collaborators per project, and we need to allocate one of those for the Bluejay tool, so it's OK if one or two people sit out. The customer projects will use a paid Tracker account that allows unlimited collaborators.)
- Link the Tracker project to the GitHub repo as described here, using the Branches integration. This will allow easily associating each Tracker story (feature) with its own GitHub feature branch automatically.
- Add the Pivotal Tracker user governifyauditor as an Owner of your Tracker project. This is for Bluejay integration, discussed later.
Deploy to Heroku
Make the changes necessary to your Gemfile for deploying to production on Heroku:
# make sure references to sqlite3 gem ONLY appear in dev/test groups
group :development, :test do
# make sure the following gems are in your production group:
group :production do
gem 'pg' # use PostgreSQL in production (Heroku)
bundle install --without production if you’ve changed your
Gemfile. Commit the changes to
Gemfile.lock. On future changes to the Gemfile, you can just say
bundle with no arguments, since Bundler will remember the option to skip production gems.
heroku apps:create appname to create your new app on Heroku. Give your team Collaborator access on Heroku so they can also deploy.
git push heroku master (or
main if that is your main branch) to ensure the app deploys correctly. Visit the app's home page and verify it behaves the same as locally. (The first time you deploy, it may take several minutes as Heroku needs to install all your gems. Future deploys are faster since only new or changed gems must be installed.)
Important. For the Bluejay tool we will set up later, add firstname.lastname@example.org as a "Collaborator" on your Heroku app.
Set up support for testing
- Add support in your Gemfile for Cucumber, RSpec, and code coverage, and re-run Bundler to install the gems:
# setup Cucumber, RSpec, Guard support
group :test do
gem 'simplecov', :require => false
gem 'cucumber-rails', :require => false
gem 'cucumber-rails-training-wheels' # basic imperative step defs like "Then I should see..."
gem 'database_cleaner' # required by Cucumber
2. If all is well, create the subdirectories and files used by RSpec and Cucumber:
rails generate rspec:install
rails generate cucumber:install
rails generate cucumber_rails_training_wheels:install
bundle exec guard init rspec
Note: the above commands will add a number of files to your app. Make sure you add them in Git. Commit. Push. Deploy to make sure it all still works.
3. Set up SimpleCov to enable test coverage measurement. (Note: you only need to measure coverage when running your tests—not when your app is actually executing. This will save you a step in the setup instructions for SimpleCov.)
rspec should be error-free, and should generate a file
coverage/index.html that you can view in a browser to see your (initially pathetically low) test coverage.
Recommended: explicitly exclude the
coverage directory from Git by adding it to
.gitignore. For this simple assignment it doesn't matter, but get used to doing this for real repos.
Set Up CI (Travis) and Code Quality reporting (CodeClimate)
1. Someone on the team (perhaps the person who owns the team repo) should also sign up for free accounts on Travis-CI.org (soon to be .com) and CodeClimate.com (you're interested in the "maintainability" product, not the "velocity" product, for CodeClimate). Point CodeClimate at your app's repo. Add a CodeClimate "maintainability" badge to the repo's README so you can always see the latest maintainability score. Strongly recommended: use your GitHub login for these.
2. For CI, use the "multiple test suites" instructions here, where the test suite commands inside the
script element should be
rspec just as you ran them locally. Note: as always, do not mindlessly copy and paste the example files in the docs. Understand what the different lines in the file are doing and which ones may need to be adjusted for your specific repo. This step may take some trial and error. You can tell if CI is working because on your Travis CI home page you will at least see that a “build” (CI run) has started for your project shortly after the first GitHub push that includes a valid
.travis.yml file. However, we've seen problems where it can take minutes or hours for the CI run to move from "queued" to "starting", but you should at least be able to verify that it's queued.
Check: making a trivial change to a file and pushing to the main branch should trigger a successful CI run (that doesn't run any tests), and eventually update the "CI - passing" badge and the Test Coverage % badge on your repo's README (home) page.
Ensure Heroku deployment still works by redeploying the app to Heroku.
Set up Bluejay
Bluejay is an experimental tool to help you track how well your team is following Agile best practices. It tracks your team's activities across various tools, including Pivotal Tracker, GitHub, Travis CI, and Heroku, to help you follow a regular and disciplined workflow.
In your repo, place a completed
info.yml file at the top level of the main branch containing the info shown in this example. For this assignment, fill in as follows: project name
q2q (get it?), owner
cs169, team ID is your team number (see your group name in bCourses); under
identities, fill in the fully qualified URLs for your Tracker project, Heroku app name, and Travis CI project. You can omit the
codecov info for now. Please specify only a single team member in the members section for this assignment.
When you believe you have a valid info.yml pushed to the top level of your main branch, enter your repo's URL in the info.yml Validator and ensure it's valid.
- Next, connect your repo to Bluejay and (suggested) put the Bluejay badge code into your repo's README.md, which will allow you to easily click over to the Bluejay dashboard. Verify that you can indeed log in to the Bluejay dashboard with the (pathetically weak) username and password provided. Hey, this isn't classified work and your repo is public anyway…
The current Bluejay configuration will help your team track how well it is following these recommended practices:
- Pivotal Tracker-based workflow. Assuming <==> means "75% of the time, these events happen within at most 1 day of each other", Bluejay will track and detect the following:
- Story marked Started on Tracker <==> feature branch created in Git. (To make the Tracker/GitHub integration work, remember that a branch for story ID 123123 must be named 123123-some-branch-name.
- Story marked Finished in Tracker <==> Creation of a PR on GitHub
- Story marked Delivered in Tracker <==> PR merged to main branch <==> App deployed to Heroku
- 75% of Travis builds should pass successfully. (Trivial for this assignment, but in real life, this ensures you're not using CI as a debugging tool but as a backstop to catch issues you didn't detect when doing local testing.)
Doing the dry run of an iteration
OK, now you can actually do the dry run!
Here's what you'll do, for each person listed as a collaborator on the Tracker project (will be no more than 4, due to the limitations of free Tracker projects):
- Create a story in Tracker to do a simple change, like "Add my name to the apps' home page". It's fine to make these all 1-point stories.
- One person or pair claims the story in Tracker and marks it Started…
- ...and creates an appropriately named feature branch in GitHub. Specifically, branch names should begin with the Tracker story ID, as described in the Tracker GitHub Integrations article
- Add the (simple) code on that branch, e.g. adding a name or two to the app's splash screen
- Push the changes to the feature branch, ideally triggering CI & coverage
- Do a pull request to the main branch once CI & coverage look good
- Get at least one other team member to sign off with LGTM ("looks good to me") in the PR, then merge it
- Deploy to Heroku from main, and verify that the change is correctly reflected
As you do this, your repo's Bluejay dashboard will try to track your adherence to the practices above.
What to turn in
Turn in a screenshot of the Bluejay dashboard and a screenshot of your app on Heroku at the end of N times through the above workflow.