Workflow

Development

Running the local server

To run the server locally, install Jekyll (you can get it with gem install github-pages), then:

jekyll serve --baseurl=''

You can then view the site at http://localhost:4000/

Custom Configuration

You can create a local configuration to override Jekyll site configuration variables, for instance to use a different API base URL and key, create a _config.local.yml that looks like:

API:
  baseurl: https://api.data.gov/some-api-url/
  key: your-api-key

Then run:

jekyll serve --baseurl='' --config _config.yml,_config.local.yml

Jekyll watches the HTML and Sass source files, and will rebuild the site automatically whenever you update them.

Updating the JavaScript

The JavaScript source files are contained in js/src, but the files that the site loads are generated with a suite of Node.js tools. To install them, run these commands from the project root:

npm install
npm install --dev

When that's done, you can rebuild the JS files once with:

npm run build

Or you can run the watcher, which will detect changes and incrementally rebuild as you work on them:

npm run watch

⚠️ You must commit the built JavaScript files (js/picc.js and its accompanying source map, js/picc.js.map) in order for your change to propagate to the site.

Workflow

Filing a Pull Request

All changes should originate as one or more pull requests ("PRs") to the dev branch. Please follow these conventions:

• If you've fixed any specific issues, please reference them either in your commit messages or in the PR description. These are some good examples.

• If you want to let people know what you're working on and solicit code reviews, consider filing a "work in progress" PR and prefixing its title with [WIP].

  • This will trigger a run of the functional tests on Travis, and if the tests fail you can continue to push to that branch to re-run them.

  • If the remaining work on your WIP PR can be broken down into discrete tasks, consider using task lists and checking off each one as they're done.

  • If you have access to Federalist, you can preview your work with the following URL template:

    https://federalist.18f.gov/preview/18F/college-choice/{branch}/
    

  • When your PR is no longer a work in progress, remove the [WIP] prefix from the title and assign somebody on the project team to review and pull it.

  • ⚠️ Thanks to our build process, JavaScript changes will likely cause merge conflicts with the dev branch. You can typically resolve these with this sequence of commands, assuming you're working on a checked in feature branch. Be sure to stop your npm run watch command first with ctrl-C first!

    # check out the dev branch
    git checkout dev
    # update your local branch
    git pull
    # switch back to your feature branch
    git checkout my-feature
    # merge dev -> your branch
    git merge dev
    # if you see merge conflicts in js/picc.js and/or js/picc.js.map, rebuild:
    npm run build
    # then add the generated files:
    git add js/picc.js*
    # and finish up the merge commit
    git commit

• After your changes have been merged to dev, you and/or a designated project team member should test them again on Federalist.

• When the PR is merged or closed, delete the feature branch using this button:

  

Tagging Releases

New releases are periodically tagged on the dev branch before merging to staging for acceptance testing. Here's the process:

1. Draft a new release:

• Version numbers should follow semantic versioning rules.

• Include the date in the release title, e.g. v1.3.0 (September 9, 2015).

• Include a list of the changes since the last release. You can view the list of commits between version numbers with this URL template:

  https://github.com/18F/collegescorecard/compare/{old}...{new}
  

  Where {old} and {new} are tags (e.g. v1.2.4) or branches (dev, staging). This is where having issues listed in the commit messages can be really helpful!

1. Create a pull request to merge your tagged release into the staging branch.

• The title of the PR follow this template: [staging] merge {version}.
• Reference the tagged release in the description.
• Here's an example.

Staging

Once a PR has been merged to the staging branch, it will be ready for another round of acceptance testing on Federalist.

Production

Pushes to production occur automatically on Federalist whenever any new commits (including PRs) are made to the master branch. The process is pretty much exactly the same as with staging:

1. Create a pull request to merge your tagged release into the master branch.

• The title of the PR follow this template: [production] merge {version}.
• Reference the tagged release in the description.
• Here's an example.