Document contributing workflow and add release helper

Author: kvz

CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+Thanks for helping improve the Transloadit Ruby SDK! This guide covers local development, testing, and publishing new releases.
+
+## Local Development
+
+After cloning the repository, install dependencies and run the test suite:
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+To exercise the signature parity suite against the Node.js CLI, make sure `npx transloadit` is available and run:
+
+```bash
+TEST_NODE_PARITY=1 bundle exec rake test
+```
+
+You can warm the CLI cache ahead of time:
+
+```bash
+TRANSLOADIT_KEY=... TRANSLOADIT_SECRET=... \
+  npx --yes transloadit smart_sig --help
+TRANSLOADIT_KEY=... TRANSLOADIT_SECRET=... \
+  npx --yes transloadit sig --algorithm sha384 --help
+```
+
+Set `COVERAGE=0` to skip coverage instrumentation if desired:
+
+```bash
+COVERAGE=0 bundle exec rake test
+```
+
+## Docker Workflow
+
+The repository ships with a helper that runs tests inside a reproducible Docker image:
+
+```bash
+./scripts/test-in-docker.sh
+```
+
+Pass a custom command to run alternatives (Bundler still installs first):
+
+```bash
+./scripts/test-in-docker.sh bundle exec ruby -Itest test/unit/transloadit/test_request.rb
+```
+
+The script forwards environment variables such as `TEST_NODE_PARITY` and credentials from `.env`, so you can combine parity checks and integration tests. End-to-end uploads are enabled by default; unset them by running:
+
+```bash
+RUBY_SDK_E2E=0 ./scripts/test-in-docker.sh
+```
+
+## Live End-to-End Test
+
+To exercise the optional live upload:
+
+```bash
+RUBY_SDK_E2E=1 TRANSLOADIT_KEY=... TRANSLOADIT_SECRET=... \
+  ./scripts/test-in-docker.sh bundle exec ruby -Itest test/integration/test_e2e_upload.rb
+```
+
+The test uploads `chameleon.jpg`, resizes it, and asserts on a real assembly response.
+
+## Releasing to RubyGems
+
+1. Update the version and changelog:
+   - Bump `lib/transloadit/version.rb`.
+   - Add a corresponding entry to `CHANGELOG.md`.
+2. Run the full test suite (including Docker, parity, and e2e checks as needed).
+3. Commit the release changes and tag:
+   ```bash
+   git commit -am "Release X.Y.Z"
+   git tag -a vX.Y.Z -m "Release X.Y.Z"
+   ```
+4. Push the commit and tag:
+   ```bash
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+5. Publish the gem using the helper script:
+   ```bash
+   GEM_HOST_API_KEY=... ./scripts/notify-registry.sh
+   ```
+6. Draft a GitHub release from the new tag and publish the generated notes.
+
+### RubyGems Credentials
+
+- You must belong to the `transloadit` organization on RubyGems with permission to push the `transloadit` gem.
+- Generate an API key with **Push Rubygems** permissions at <https://rubygems.org/profile/edit>. Copy the token and keep it secure.
+- Export the token as `GEM_HOST_API_KEY` in your environment before running `./scripts/notify-registry.sh`. The script refuses to run if the variable is missing.
+
+That’s it! Thank you for contributing.
+

README.md

@@ -467,71 +467,4 @@ If you still need support for Ruby 2.x, 2.0.1 is the last version that supports
 
 ## Contributing
 
-Contributions are welcome!
-
-### Running tests
-
-```bash
-bundle install
-bundle exec rake test
-```
-
-To also test parity against the Node.js reference implementation, ensure you can run `npx transloadit smart_sig` and `npx transloadit sig` (the CLI downloads on demand), then run:
-
-```bash
-TEST_NODE_PARITY=1 bundle exec rake test
-```
-
-You can warm the CLI cache ahead of time with:
-
-```bash
-TRANSLOADIT_KEY=... TRANSLOADIT_SECRET=... \
-  npx --yes transloadit smart_sig --help
-TRANSLOADIT_KEY=... TRANSLOADIT_SECRET=... \
-  npx --yes transloadit sig --algorithm sha384 --help
-```
-
-To disable coverage reporting, run:
-
-```bash
-COVERAGE=0 bundle exec rake test
-```
-
-#### Run tests in Docker
-
-```bash
-./scripts/test-in-docker.sh
-```
-
-This builds a local image, runs `bundle install`, and executes `bundle exec rake test`. Pass a custom command to run something else (Bundler still installs first):
-
-```bash
-./scripts/test-in-docker.sh bundle exec ruby -Itest test/unit/transloadit/test_request.rb
-```
-
-The script forwards environment variables such as `TEST_NODE_PARITY` or credentials defined in `.env`, so you can combine parity checks and integration tests inside Docker:
-
-```bash
-TEST_NODE_PARITY=1 ./scripts/test-in-docker.sh
-```
-
-To exercise the optional end-to-end upload against a real Transloadit account, provide `TRANSLOADIT_KEY` and `TRANSLOADIT_SECRET` (via environment variables or `.env`) and set `RUBY_SDK_E2E=1`:
-
-```bash
-RUBY_SDK_E2E=1 ./scripts/test-in-docker.sh bundle exec ruby -Itest test/integration/test_e2e_upload.rb
-```
-
-The test uploads `chameleon.jpg`, resizes it, and asserts on the live assembly results.
-
-> **Note:** `./scripts/test-in-docker.sh` now defaults to `RUBY_SDK_E2E=1`. If you want to skip the live upload during local runs, invoke `RUBY_SDK_E2E=0 ./scripts/test-in-docker.sh` instead.
-
-### Releasing on RubyGems
-
-Let's say you wanted to release version `3.1.0`, here are the steps:
-
-1. Update the version number in the version file `version.rb` and `CHANGELOG.md`
-2. Commit: `git add CHANGELOG.md lib/transloadit/version.rb && git commit -m "Release 3.1.0"`
-3. Create a git tag: `git tag -a v3.1.0 -m "Release 3.1.0"`
-4. Push the git tag: `git push origin v3.1.0`
-5. Release on RubyGems: `gem build transloadit.gemspec && gem push transloadit-3.1.0.gem`
-6. Draft a release [here](https://github.com/transloadit/ruby-sdk/releases). Click the `v3.1.0` tag and click `Generate release notes`. Inspect and Publish.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, testing, and release instructions.

scripts/notify-registry.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE_NAME=${IMAGE_NAME:-transloadit-ruby-sdk-dev}
+
+err() {
+  echo "notify-registry: $*" >&2
+}
+
+if ! command -v docker >/dev/null 2>&1; then
+  err "Docker is required to publish the gem."
+  exit 1
+fi
+
+if [[ -z "${GEM_HOST_API_KEY:-}" ]]; then
+  err "GEM_HOST_API_KEY environment variable is not set. Generate a RubyGems API key with push permissions and export it before running this script."
+  exit 1
+fi
+
+if ! docker image inspect "$IMAGE_NAME" >/dev/null 2>&1; then
+  err "Docker image '$IMAGE_NAME' not found. Building it now..."
+  docker build -t "$IMAGE_NAME" -f Dockerfile .
+fi
+
+version=$(
+  docker run --rm \
+    -v "$PWD":/workspace \
+    -w /workspace \
+    "$IMAGE_NAME" \
+    ruby -Ilib -e 'require "transloadit/version"; puts Transloadit::VERSION'
+)
+
+gem_file="transloadit-${version}.gem"
+
+err "Building ${gem_file}..."
+docker run --rm \
+  --user "$(id -u):$(id -g)" \
+  -e HOME=/workspace \
+  -v "$PWD":/workspace \
+  -w /workspace \
+  "$IMAGE_NAME" \
+  bash -lc "set -euo pipefail; rm -f ${gem_file}; gem build transloadit.gemspec >/dev/null"
+
+err "Pushing ${gem_file} to RubyGems..."
+docker run --rm \
+  --user "$(id -u):$(id -g)" \
+  -e HOME=/workspace \
+  -e GEM_HOST_API_KEY="$GEM_HOST_API_KEY" \
+  -v "$PWD":/workspace \
+  -w /workspace \
+  "$IMAGE_NAME" \
+  bash -lc "set -euo pipefail; gem push ${gem_file}"
+
+err "Removing local ${gem_file}..."
+rm -f "${gem_file}"
+
+echo "notify-registry: Successfully pushed ${gem_file} to RubyGems."