Skip to content

docs: add a runnable Ruby Gemfile walkthrough #25

Description

@fly1d

User workflow

A Ruby or Bundler maintainer wants to shrink a Gemfile around a dependency
failure, then verify the exported reproduction before sharing it. The
repository already has a deterministic, network-free fixture at
benchmarks/ruby-gemfile,
but the main examples guide does not currently show the end-to-end Ruby
manifest workflow.

Scope

Add one concise, copy-pasteable Ruby Gemfile section to
docs/EXAMPLES.md.
Reuse the existing fixture, --adapter ruby, and its Ruby oracle. Keep this
documentation-only: do not add dependencies, invoke Bundler, install gems, or
change reducer semantics.

The section should show, from the repository root:

  • checking that ruby is available before running the example;
  • creating a temporary output parent outside the fixture;
  • running the existing reduction with the stable ORIGINAL_FAILURE marker;
  • the two retained files (Gemfile and reproduce.rb);
  • the retained repomin-required declaration, representative removed
    single-line declarations, and the current unchanged constructs outside the
    adapter's mutation set (including the multiline gem call and gemspec);
  • report validate --payload --json, including the expected valid/exact
    fingerprint evidence; and
  • an independent oracle rerun from the exported payload, with expected exit
    code 1 and ORIGINAL_FAILURE in command output.

Explain that this fixture reads the Gemfile text with a local Ruby oracle,
so it exercises structural declaration reduction without Bundler, gem
installation, RubyGems index access, gem-source access, lifecycle hooks, or
external network. It is adapter evidence for the configured oracle, not proof
that an arbitrary minimized Bundler project resolves, installs, or behaves
correctly. Link the fixture README and the host-backend boundary in
SECURITY.md.

Do not pin attempt counts, byte counts, cache hits, or Gemfile whitespace;
those are not the user contract and may change as the reducer evolves.

Acceptance criteria

  • docs/EXAMPLES.md contains one complete Ruby Gemfile workflow runnable
    from the repository root.
  • The example keeps output outside benchmarks/ruby-gemfile and documents
    the exact retained files and required/removed declaration semantics.
  • The validation and independent-rerun commands are copy-pasteable, with
    their expected fingerprint mode, marker, and exit behavior stated
    accurately.
  • The text clearly states the Ruby-runtime/Bundler/install/network boundary
    and the descriptive oracle/security limitations.
  • python3 scripts/check_docs.py passes.
  • python3 benchmarks/run_offline.py --only ruby-gemfile passes, or is
    reported as skipped when a Ruby runtime is unavailable.
  • The change remains documentation-only and does not duplicate the fixture
    README verbatim.

Before starting, comment here so the scope stays coordinated. In the PR,
include Closes #<issue-number> and paste the two check results. If a command
cannot be run locally, say exactly what was skipped and why.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions