[OMBU-821] Document setup and add benchmark examples - #20
Merged
Conversation
bin/setup failed for new contributors (#10). The yarn half of that is fixed by removing webpacker, which took config/webpacker.yml and its check_yarn_integrity hook with it; ./bin/setup now completes. The other half was undocumented: config/database.yml is gitignored, so db:prepare fails until you create one, and nothing said so. The README now covers what the app is for, how to share a benchmark, the database.yml step, how to run the suite against both Rails versions, and the POST /reports contract. It also documents verifying a change end to end, which the suite cannot do: it uses Rack::Test, so it never exercises a real server or a real client. Adds examples/ with two runnable benchmarks, since a first-time user otherwise has to invent one: smoke_benchmark.rb four ways to build a string, with x.compare! legacy_client_benchmark.rb the same pinned to benchmark-ips 2.14.0, to exercise the pre-2.15.0 request shape Pinning matters there: `require` activates the newest installed version, so installing the old gem alongside a newer one does not exercise the old path. Also drops babel.config.js and postcss.config.js, webpacker build configs missed when webpacker was removed.
Rails generates bin/dev as a foreman wrapper around Procfile.dev, which exists to run an asset watcher next to the server. This app no longer has one, so that would mean adding a foreman dependency to supervise a single process. This is a plain launcher instead. It earns its place by catching the trap from #10: a missing config/database.yml otherwise fails partway through boot, and the file is gitignored, so a fresh clone always hits it. bin/dev checks first and prints the fix. Arguments pass through, so `bin/dev -p 4000` works.
bin/dev already refused to start without config/database.yml, but bin/setup runs first and still failed inside db:prepare with a stack trace. Both entry points now stop with the same message, and it is self-contained rather than pointing at the README, so the README no longer needs to spell the step out.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #10
The issue
./bin/setupfailed for new contributors with a yarn integrity error, then a faileddb:prepare. Two separate causes:check_yarn_integrityhook inconfig/webpacker.yml. Removing webpacker in [OMBU-821] Upgrade to Ruby 4.0.6 #19 took that file with it, so this half is already fixed on main. Confirmed:./bin/setupnow exits 0.db:preparefailure was never documented.config/database.ymlis gitignored, so setup fails until you create one, and nothing in the README said so. This PR documents it.README
Rewritten to be usable by someone who has never seen the app: what it is for, how to share a benchmark with benchmark-ips, the
config/database.ymlstep, running the suite against both Rails versions, and thePOST /reportscontract.Adds a Verifying a change end to end section, because the suite cannot do it: it uses Rack::Test, so it never exercises a real server or a real client. That section covers
SHARE_URLagainst a local server or a deployed instance, plusheroku logsandbin/rails runnerto confirm what was stored.Also notes that report ids are base58 row ids, so early ones on a fresh instance are a single character like
/2. That reads like a broken link when it is not.examples/
A first-time user otherwise has to invent a benchmark before they can try anything.
examples/smoke_benchmark.rbx.compare!. Checks an instance accepts and renders a report.examples/legacy_client_benchmark.rbThe pin in the second file is load-bearing:
requireactivates the newest installed version, so installing 2.14.0 alongside a newer gem does not exercise the old path. Worth knowing for anyone touchingfix_missing_json_content_type, since that is what therack ~> 2.2pin protects.Also
Drops
babel.config.jsandpostcss.config.js, two webpacker build configs missed when webpacker was removed.No application code changes. Suite green on Ruby 4.0.6 for both Rails versions: 21 runs, 37 assertions.