h2o is open-source software designed to replace bulky and expensive law textbooks with an easy-to-use web interface where instructors and students alike can author, organize, view and print public-domain course material.
Auto-deploy of the latest master. If the build is green, it's up-to-date.
TODO: These instructions are incomplete for dev platforms other than OS X, and probably lack steps needed on a fresh machine.
Set up RVM
- Install RVM (if missing) with
\curl -sSL https://get.rvm.io | bash -s stable --auto-dotfiles, then
- Install the project Ruby version (e.g.
rvm install $(<.ruby-version))
cdinto the h2o directory (or
cd .if already there) to create the gemset.
Install gems with Bundler
gem install bundler && bundle install
- (If Bundler complains about missing library dependencies, install them and
bundle installuntil it succeeds.)
Install node and npm packages
- Installation of yarn is platform-specific. On a Mac: if you already have node installed,
brew install yarn --without-node, or
brew install yarnto simultaneously install node.
With NPM (might not install precisely the same package versions)
- Install node if needed (e.g.
brew install node)
Set up the Postgres database
- Install postgres ~9.6 (if missing). Note:
brew install postgresnow installs postgres 10+. To install 9.6.5 via Homebrew, install postgres using the specific version formula (
brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/d014fa223f77bee4b4097c5e80faa0954e28182f/Formula/postgresql.rb) and then run
brew switch postgres 9.6.5
- Start solr with
- Create and initialize the database with
- Stop solr with
rake db:setup fails with a message like
rails sunspot:solr:run to see why solr failed to start. You may need to update your java installation
brew cask install java
Set Environment Variables
- Replace the values in
.envwith your own environment variables
guard. It will take several seconds to:
- Make sure the bundle is up-to-date;
- Start the dev/test Solr server;
- Load Spring for fast
- And finally boot Rails.
- (Optionally, install a notifier such as Growl or
brew install terminal-notifierfor Guard notifications.)
- Guard will now be watching the project for changes and will restart Spring/Rails when needed. This can also be done from the guard command line, e.g.
- When finished, type
exitto shut everything down and close Guard.
Configure the local domain
- e.g. OS X:
echo 127.0.0.1 h2o-dev.local | sudo tee -a /etc/hosts
- Go to http://h2o-dev.local:8000
Since we're going to be heavily refactoring and likely removing a lot of code, the focus for now will be on high-level feature tests which will survive that. cases_test.rb is an example of the test pattern using Minitest and Capybara which exercises the full stack from a user's point of view.
ImageMagick and a global installation of the "Garamond" font are required. On Macs, you can verify the presence of Garamond in Applications > FontBook, and can install ImageMagick via
brew install imagemagick.
Test scenarios marked with
js: true will be run in a headless WebKit environment via Poltergeist. This requires the PhantomJS binary to be installed, e.g.
brew install phantomjs. Headless tests are significantly slower than static tests, so prefer to avoid writing tests (and features!) that require JS when possible.
Guard will not automatically run these tests. This is less than ideal when working on a client-side feature, so you can mark a given test with
focus: true to force Guard to run it. If no JS tests are enabled, PhantomJS will not boot, speeding up the whole test suite considerably.
Guard will automatically run all static tests after booting Rails and again after any test or app file is edited. By default, Guard won't run any tests that require JS, since they're so much slower. You can run those tests manually:
bin/rails testruns non-system tests.
bin/rails test:systemruns system tests, including JS tests.
bin/rails test test/system/cases_test.rbruns the case feature test, and so on, including JS tests.
Coverage will be generated automatically for all manually-run tests.
TODO: When coverage is a bit higher, add a git commit hook which runs the coverage report and fails if under some value.
Legacy Playlists must be converted into Casebooks. To convert all un-migrated, use this rake task:
Any Playlists that don't have a Casebook with a matching
created_at date will be migrated.
You can also migrate individual playlists from the rails console:
bin/rails c > Migrate::Playlist.find(52410).migrate => #<Content::Casebook ... > > Migrate::Playlist.find([11494, 5456, 1496]).map &:migrate => [#<Content::Casebook id: ...>, ...]
If importing data from another installation of H2O into your local database, you may need to create an h2oadmin role in postgres first (e.g.,
psql postgres, followed by
CREATE ROLE h2oadmin;. Note the terminating semi-colon).
Be advised that depending on the source of the data, some local rake tasks (e.g.
db:reset) may subsequently fail with spurious warnings about affecting production data, regardless of the current value of
Contributions to this project should be made in individual forks and then merged by pull request. Here's an outline:
- Fork and clone the project.
- Make a branch for your feature:
git branch feature-1
- Commit your changes with
git commit. (
git diff --stagedis handy here!)
- Push your branch to your fork:
git push origin feature-1
- Submit a pull request to the upstream master through GitHub.
Whenever possible, pull requests should be fast-forwarded (i.e.,
Rebase and Merged). This creates a nice, linear record of commits, without ugly merge commits that lose context and history.
In order to fast-forward a pull request,
upstream/master shouldn't have any commits that aren't also on the fork in the same order— in other words, they have to agree about the history of the repo. This is a problem if upstream has changed since you created your branch!
Rather than creating a merge commit which reconciles the changes, you'll want to
rebase your branch to
upstream/master. Rebasing simply means that you stash your new commits temporarily, fast-forward your local repo to the updated
upstream/master, and then apply your changes on top, pretending that your commits are the most recent changes.
In general, GitHub can automatically rebase a pull request, but if there are any conflicts you'll need to resolve them manually with this process:
- Add the upstream repository with
git remote add upstream
- Fetch the latest changes with
git fetch upstream
- Rebase your branch to upstream:
git rebase upstream/master
- (You can do both of these in one step with
git pull upstream master --rebase)
upstream/masterhas changes that conflict with your commits, you'll need to amend them at this time.
- Push and pull request.
In the case of particularly ugly conflicts, rebasing can be more trouble than it's worth to preserve history, and a big merge commit will be the best option, but that should be avoided whenever possible. Rebasing your local branch to
upstream/master frequently is the best way to avoid headaches later on.
This codebase is Copyright 2017 The President and Fellows of Harvard College and is licensed under the open-source AGPLv3 for public use and modification. See LICENSE for details.