Merge pull request rsim#278 from yahonda/add-contributing-md

Add CONTRIBUTING.md and trim README

Author: yahonda

CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing to ruby-plsql
+
+Thanks for your interest in contributing! This document covers how to
+report issues, open pull requests, and run the test suite locally.
+
+## Reporting issues
+
+File issues at https://github.com/rsim/ruby-plsql/issues. Please
+include:
+
+- ruby-plsql version (or commit SHA if you're on a branch)
+- Oracle Database version
+- Ruby engine and version (MRI / JRuby)
+- A minimal reproduction — runnable code, expected vs. actual behavior
+
+## Submitting pull requests
+
+1. Fork the repository and create a topic branch off `master`.
+2. Make your change. Include a regression test whenever practical.
+3. Run the full spec suite (see below) and RuboCop.
+4. Open a pull request against `rsim/ruby-plsql:master` describing
+   what changed and why.
+
+## Development with devcontainer
+
+The repository ships with a devcontainer configuration that provides a
+complete development environment with Oracle Database and all required
+dependencies pre-configured. It supports both x64 and ARM64 hosts, and
+is the recommended way to work on ruby-plsql.
+
+### Prerequisites
+
+- [Docker](https://www.docker.com/get-started) installed and running
+- [VS Code](https://code.visualstudio.com/) with the
+  [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+### Getting started
+
+1. Clone the repository:
+   ```sh
+   git clone https://github.com/rsim/ruby-plsql.git
+   cd ruby-plsql
+   ```
+2. Open the project in VS Code:
+   ```sh
+   code .
+   ```
+3. When prompted, click "Reopen in Container" — or from the Command
+   Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) run
+   "Dev Containers: Reopen in Container".
+4. VS Code builds and starts the environment automatically. This
+   includes Ruby 4.0, Oracle Database Free (latest), Oracle Instant
+   Client (latest 23.x), and all gems from `bundle install`.
+
+### What's included
+
+- **Ruby**: 4.0
+- **Oracle Database**: Free (latest)
+- **Oracle Instant Client**: latest 23.x
+- **Database configuration**:
+  - Port `1521` is forwarded from the container
+  - Service name: `FREEPDB1`
+  - System password: `Oracle18`
+  - TNS configuration in `ci/network/admin`
+  - Test users (`hr`, `arunit`) are provisioned automatically via
+    `ci/setup_accounts.sh`
+
+## Running the test suite
+
+Inside the devcontainer:
+
+```sh
+bundle exec rake spec                               # full suite
+bundle exec rspec spec/path/to/file_spec.rb         # single file
+bundle exec rspec spec/path/to/file_spec.rb:42      # single example
+```
+
+### Reproducing a specific run
+
+Specs run in randomized order. The seed is printed at the start of the
+run, e.g.:
+
+```
+==> Randomized with seed 12345 (reproduce: bundle exec rspec --seed 12345)
+```
+
+To reproduce that exact run:
+
+```sh
+bundle exec rspec --seed 12345
+```
+
+If a failure looks order-dependent, narrow it down to the minimal
+failing pair with `--bisect`:
+
+```sh
+bundle exec rspec --seed 12345 --bisect
+```
+
+The seed line is also visible in CI job logs, including partial logs
+when a run hangs and is cancelled.
+
+## Running RuboCop
+
+```sh
+BUNDLE_ONLY=rubocop bundle install
+BUNDLE_ONLY=rubocop bundle exec rubocop --parallel
+```
+
+These are the same commands CI runs (`.github/workflows/rubocop.yml`).
+
+## Manual setup (without devcontainer)
+
+If you prefer to develop against an existing Oracle Database, review
+`spec/spec_helper.rb` for the default schema/user names and database
+names (override via environment variables as needed).
+
+### Prepare the database
+
+Use any reachable Oracle Database and create the test schemas:
+
+```sql
+CREATE USER hr IDENTIFIED BY hr;
+GRANT unlimited tablespace, create session, create table,
+      create sequence, create procedure, create type,
+      create view, create synonym TO hr;
+
+CREATE USER arunit IDENTIFIED BY arunit;
+GRANT create session TO arunit;
+```
+
+The CI helper `ci/setup_accounts.sh` performs the equivalent setup
+against `${DATABASE_NAME}` using `${DATABASE_SYS_PASSWORD}`.
+
+### Prepare dependencies
+
+```sh
+gem install bundler
+bundle install
+```
+
+### Run the suite
+
+```sh
+bundle exec rake spec
+```

README.md

@@ -180,31 +180,7 @@ Make sure you use correct version of Oracle client for database you're connectin
 TESTS
 -----
 
-Review `spec/spec_helper.rb` to see default schema/user names and database names (use environment variables to override defaults)
-
-##### Prepare database
-
-In an Oracle Database create the following schemas for test purposes.
-
-        SQL> CREATE USER hr IDENTIFIED BY hr;
-        SQL> GRANT unlimited tablespace, create session, create table, create sequence, create procedure, create type, create view, create synonym TO hr;
-
-        SQL> CREATE USER arunit IDENTIFIED BY arunit;
-        SQL> GRANT create session TO arunit;
-
-##### Prepare dependencies
-
-* Install bundler with
-
-        gem install bundler
-
-* Install necessary gems with
-
-        bundle install
-
-##### Run tests
-
-        rake spec
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment and run the spec suite.
 
 LINKS
 -----
@@ -216,13 +192,7 @@ LINKS
 CONTRIBUTORS
 ------------
 
-* Raimonds Simanovskis
-* Edgars Beigarts
-* Oleh Mykytyuk
-* Wiehann Matthysen
-* Dayle Larson
-* Yasuo Honda
-* Yavor Nikolov
+Thanks to everyone who has contributed to ruby-plsql over the years. The up-to-date list is maintained on GitHub: https://github.com/rsim/ruby-plsql/graphs/contributors
 
 LICENSE
 -------