chore(internal): contribute.md and contributor QoL improvements

Author: stainless-app[bot]

.gitignore

@@ -1,10 +1,10 @@
 *.gem
 .idea/
+.ignore
 .prism.log
 .ruby-lsp/
 .yardoc/
-Brewfile.lock.json
 bin/tapioca
+Brewfile.lock.json
 doc/
-sorbet/*
-!/sorbet/config
+sorbet/tapioca/*

.ruby-version

@@ -0,0 +1 @@
+3.1.0

CONTRIBUTING.md

@@ -0,0 +1,132 @@
+## Setting up the environment
+
+This repository contains a `.ruby-version` file, which should work with either [rbenv](https://github.com/rbenv/rbenv) or [asdf](https://github.com/asdf-vm/asdf) with the [ruby plugin](https://github.com/asdf-vm/asdf-ruby).
+
+Please follow the instructions for your preferred version manager to install the Ruby version specified in the `.ruby-version` file.
+
+To set up the repository, run:
+
+```bash
+$ ./scripts/bootstrap
+```
+
+This will install all the required dependencies.
+
+## Modifying/Adding code
+
+Most of the SDK is generated code. Modifications to code will be persisted between generations, but may result in merge conflicts between manual patches and changes from the generator. The generator will never modify the contents `examples/` directory.
+
+## Adding and running examples
+
+All files in the `examples/` directory are not modified by the generator and can be freely edited or added to.
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/openai"
+
+# ...
+```
+
+```bash
+$ chmod +x './examples/<your-example>.rb'
+
+# run the example against your api
+$ ruby './examples/<your-example>.rb'
+```
+
+## Using the repository from source
+
+If you’d like to use the repository from source, you can either install from git or reference a cloned repository:
+
+To install via git in your `Gemfile`:
+
+```ruby
+gem "openai", git: "https://www.github.com/openai/openai-ruby"
+```
+
+Alternatively, reference local copy of the repo:
+
+```bash
+$ git clone -- 'https://www.github.com/openai/openai-ruby' '<path-to-repo>'
+```
+
+```ruby
+gem "openai", path: "<path-to-repo>"
+```
+
+## Running commands
+
+Running `rake` by itself will show all runnable commands.
+
+```bash
+$ bundle exec rake
+```
+
+## Running tests
+
+Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
+
+```bash
+$ npx prism mock path/to/your/openapi.yml
+```
+
+```bash
+$ bundle exec rake test
+```
+
+## Linting and formatting
+
+This repository uses [rubocop](https://github.com/rubocop/rubocop) for linting and formatting of `*.rb` and `*.rbi` files. [syntax_tree](https://github.com/ruby-syntax-tree/syntax_tree) is used for formatting `*.rbs` files.
+
+There are two separate type checkers supported by this library: [sorbet](https://github.com/sorbet/sorbet) and [steep](https://github.com/soutaro/steep) are used for verifying `*.rbi` and `*.rbs` files respectively.
+
+To lint and typecheck:
+
+```bash
+$ bundle exec rake lint
+```
+
+To format and fix all lint issues automatically:
+
+```bash
+$ bundle exec rake format
+```
+
+## Editor Support
+
+### Solargraph
+
+This library includes [Solargraph](https://solargraph.org) support for both auto-completion and go to definition.
+
+```ruby
+gem "solargraph", group: :development
+```
+
+Note: if you had installed the gem locally using `git: "..."` or `path: "..."`, you must update your [`.solargraph.yml`](https://solargraph.org/guides/configuration) to include the path to where the gem is located:
+
+```yaml
+include:
+  - '<path-to-repo>/lib/**/*.rb'
+```
+
+### Sorbet
+
+[Sorbet](https://sorbet.org) should mostly work out of the box when editing this library directly. However, there are a some caveats due to the colocation of `*.rb` and `*.rbi` files in the same project. These issues should not otherwise manifest when this library is used as a dependency.
+
+1. For go to definition usages, sorbet might get confused and may not always navigate to the correct location.
+
+2. For each generic type in `*.rbi` files, a spurious "Duplicate type member" error is present.
+
+### Ruby LSP
+
+The Ruby LSP has [best effort support](https://shopify.github.io/ruby-lsp/#guessed-types) for inferring type information from Ruby code, and as such it may not always be able to provide accurate type information.
+
+## Documentation Preview
+
+To preview the documentation, run:
+
+```bash
+$ bundle exec rake docs:preview [PORT=8808]
+```

Rakefile

@@ -1,16 +1,30 @@
 # frozen_string_literal: true
 
+require "pathname"
 require "securerandom"
 require "shellwords"
 
 require "minitest/test_task"
 require "rake/clean"
 require "rubocop/rake_task"
 
-CLEAN.push(*%w[.idea/ .ruby-lsp/ .yardoc/])
+tapioca = "sorbet/tapioca"
+ignore_file = ".ignore"
 
-multitask(default: [:test])
+CLEAN.push(*%w[.idea/ .ruby-lsp/ .yardoc/ doc/], *FileList["*.gem"], ignore_file)
 
+CLOBBER.push(*%w[sorbet/rbi/annotations/ sorbet/rbi/gems/], tapioca)
+
+multitask(:default) do
+  sh(*%w[rake --tasks])
+end
+
+desc("Preview docs; use `PORT=<PORT>` to change the port")
+multitask(:"docs:preview") do
+  sh(*%w[yard server --bind [::] --reload --quiet --port], ENV.fetch("PORT", "8808"))
+end
+
+desc("Run test suites; use `TEST=path/to/test.rb` to run a specific test file")
 multitask(:test) do
   rb =
     FileList[ENV.fetch("TEST", "./test/**/*_test.rb")]
@@ -23,17 +37,20 @@ end
 rubo_find = %w[find ./lib ./test ./rbi -type f -and ( -name *.rb -or -name *.rbi ) -print0]
 xargs = %w[xargs --no-run-if-empty --null --max-procs=0 --max-args=300 --]
 
-multitask(:rubocop) do
+desc("Lint `*.rb(i)`")
+multitask(:"lint:rubocop") do
   lint = xargs + %w[rubocop --fail-level E] + (ENV.key?("CI") ? %w[--format github] : [])
   sh("#{rubo_find.shelljoin} | #{lint.shelljoin}")
 end
 
-multitask(:ruboformat) do
+desc("Format `*.rb(i)`")
+multitask(:"format:rubocop") do
   fmt = xargs + %w[rubocop --fail-level F --autocorrect --format simple --]
   sh("#{rubo_find.shelljoin} | #{fmt.shelljoin}")
 end
 
-multitask(:syntax_tree) do
+desc("Format `*.rbs`")
+multitask(:"format:syntax_tree") do
   find = %w[find ./sig -type f -name *.rbs -print0]
   inplace = /darwin|bsd/ =~ RUBY_PLATFORM ? %w[-i''] : %w[-i]
   uuid = SecureRandom.uuid
@@ -74,27 +91,49 @@ multitask(:syntax_tree) do
   fail unless success
 end
 
-multitask(format: [:ruboformat, :syntax_tree])
+desc("Format everything")
+multitask(format: [:"format:rubocop", :"format:syntax_tree"])
 
-multitask(:steep) do
+desc("Typecheck `*.rbs`")
+multitask(:"typecheck:steep") do
   sh(*%w[steep check])
 end
 
-multitask(:sorbet) do
+desc("Typecheck `*.rbi`")
+multitask(:"typecheck:sorbet") do
   sh(*%w[srb typecheck])
 end
 
-file("sorbet/tapioca") do
+file(tapioca) do
   sh(*%w[tapioca init])
 end
 
-multitask(typecheck: [:steep, :sorbet])
-multitask(lint: [:rubocop, :typecheck])
+desc("Typecheck everything")
+multitask(typecheck: [:"typecheck:steep", :"typecheck:sorbet"])
+
+desc("Lint everything")
+multitask(lint: [:"lint:rubocop", :typecheck])
+
+desc("Build yard docs")
+multitask(:"build:docs") do
+  sh(*%w[yard])
+end
+
+desc("Build ruby gem")
+multitask(:"build:gem") do
+  # optimizing for grepping through the gem bundle: many tools honour `.ignore` files, including VSCode
+  #
+  # both `rbi` and `sig` directories are navigable by their respective tool chains and therefore can be ignored by tools such as `rg`
+  Pathname(ignore_file).write(<<~GLOB)
+    rbi/*
+    sig/*
+  GLOB
 
-multitask(:build) do
   sh(*%w[gem build -- openai.gemspec])
+  rm_rf(ignore_file)
 end
 
-multitask(release: [:build]) do
+desc("Release ruby gem")
+multitask(release: [:"build:gem"]) do
   sh(*%w[gem push], *FileList["openai-*.gem"])
 end

openai.gemspec

@@ -8,12 +8,21 @@ Gem::Specification.new do |s|
   s.summary = "Ruby library to access the OpenAI API"
   s.authors = ["OpenAI"]
   s.email = "[email protected]"
-  s.files = Dir["lib/**/*.rb", "rbi/**/*.rbi", "sig/**/*.rbs", "manifest.yaml", "CHANGELOG.md", "SECURITY.md"]
-  s.extra_rdoc_files = ["README.md"]
-  s.required_ruby_version = ">= 3.0.0"
-  s.add_dependency "connection_pool"
   s.homepage = "https://gemdocs.org/gems/openai"
   s.metadata["homepage_uri"] = s.homepage
   s.metadata["source_code_uri"] = "https://github.com/openai/openai-ruby"
   s.metadata["rubygems_mfa_required"] = false.to_s
+  s.required_ruby_version = ">= 3.0.0"
+
+  s.files = Dir[
+    "lib/**/*.rb",
+    "rbi/**/*.rbi",
+    "sig/**/*.rbs",
+    "manifest.yaml",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    ".ignore"
+  ]
+  s.extra_rdoc_files = ["README.md"]
+  s.add_dependency "connection_pool"
 end

scripts/bootstrap

@@ -2,7 +2,7 @@
 
 set -e
 
-cd "$(dirname "$0")/.."
+cd -- "$(dirname -- "$0")/.."
 
 if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ]; then
   brew bundle check >/dev/null 2>&1 || {
@@ -13,4 +13,4 @@ fi
 
 echo "==> Installing Ruby dependencies…"
 
-bundle install
+exec -- bundle install "$@"

scripts/format

@@ -5,4 +5,5 @@ set -e
 cd -- "$(dirname -- "$0")/.."
 
 echo "==> Running formatters"
+
 exec -- bundle exec rake format "$@"

scripts/lint

@@ -4,4 +4,6 @@ set -e
 
 cd -- "$(dirname -- "$0")/.."
 
+echo "==> Running linters"
+
 exec -- bundle exec rake lint "$@"

scripts/test

@@ -2,7 +2,7 @@
 
 set -e
 
-cd "$(dirname "$0")/.."
+cd -- "$(dirname -- "$0")/.."
 
 RED='\033[0;31m'
 GREEN='\033[0;32m'

sorbet/rbi/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore