Conversation
sandbergja
left a comment
sandbergja
left a comment
There was a problem hiding this comment.
Thanks, @jcoyne ! Two thoughts, neither of them are blockers.
|
|
||
| ## What this is | ||
|
|
||
| Blacklight is a **Ruby on Rails engine gem** (the `blacklight` rubygem) **plus an npm package** (`blacklight-frontend`) providing the Solr discovery UI. The two ship together. Active development for 9.x is on `main`; older series live on `release-8.x` / `release-7.x` branches. Ruby >= 3.3, Rails >= 7.2 and < 9. |
There was a problem hiding this comment.
It's nice to give the agent these specifics, but I'm wondering if we'll forget to update the branches when we set up Blacklight 10, and the minimum versions whenver these change. And it strikes me that the minimum versions at least are quite simple for an agent to figure out -- maybe not worth the maintenance burden to include them here?
| ## Testing prerequisites (the main gotchas) | ||
|
|
||
| - The suite runs **inside a generated Rails app** at `.internal_test_app/` (gitignored), produced by `engine_cart`; `spec/spec_helper.rb` calls `EngineCart.load_application!`. If it doesn't exist, generate it first: `bundle exec rake engine_cart:generate`. | ||
| - Specs need **Solr running** with the `analysis-extras` module. `rake ci` / `rake server` start it via docker compose (preferred) or `solr_wrapper`. To point the suite at an already-running Solr, set `SOLR_ENV=docker-compose` (used by `compose.yaml`). | ||
| - Feature specs use **Capybara headless Chrome** (`selenium-webdriver`) — Chrome must be installed. | ||
| - Seed data is indexed by `rake blacklight:internal:seed` (source: `spec/fixtures/sample_solr_documents.yml`). | ||
|
|
||
| ### Environment variables that change behavior | ||
|
|
||
| - `RAILS_VERSION`, `SOLR_VERSION`, `VIEW_COMPONENT_VERSION`, `BOOTSTRAP_VERSION`, `BUNDLER_VERSION` — select dependency versions (see `.github/matrix.json`). | ||
| - `BLACKLIGHT_API_TEST=1` — run only API-mode tests (tagged `:api`). | ||
| - `ENGINE_CART_RAILS_OPTIONS` — flags passed to the generated test app (e.g. `--api`, `--css=bootstrap`). | ||
| - `COVERAGE=true` — enable SimpleCov (set by `rake blacklight:coverage`). |
There was a problem hiding this comment.
I'm glad that we are documenting these in the repo, seems nice for a 🤖 or a human!
There was a problem hiding this comment.
I agree, can't we document these in the README?
tpendragon
left a comment
tpendragon
left a comment
There was a problem hiding this comment.
Do we need this? Doesn't it work well enough that we don't have to explicitly encourage agent usage? Or at least, can we think about some policy that may hit this file which requires being transparent about it?
tpendragon
left a comment
tpendragon
left a comment
There was a problem hiding this comment.
Also there's recent research that shows agents.md may actually make agents worse.
Why would we even want to give better documentation to claude than to humans?
3 participants
This cuts down on some of the research an agent would have to do before getting down to work.