docs: review and improve CONTRIBUTING.md (#10)

Author: devmatteini

CONTRIBUTING.md

@@ -2,30 +2,47 @@
 
 Welcome, we really appreciate if you're considering to contribute to effect-mongodb!
 
-## Setting Up Your Environment
+- [Initial setup](#initial-setup)
+- [Making changes](#making-changes)
+- [Tests](#tests)
 
-1. Fork this repo
-2. Clone your forked repo
+## Initial setup
+
+Install the following tools to set up your environment:
+
+- [Node.js](https://nodejs.org/en) 20 or newer
+- [pnpm](https://pnpm.io/) 9.4.0 or newer
+- [Docker](https://www.docker.com/) for running tests using `@testcontainers/mongodb`
+
+Then, you can fork the repository and install the dependencies:
+
+1. Fork this repository on GitHub
+2. Clone your forked repo:
    ```shell
    git clone https://github.com/<username>/effect-mongodb && cd effect-mongodb
    ```
-3. Create a new branch
-    ```shell
-    git checkout -b my-branch
-    ```
-4. Install dependencies
+3. Install dependencies:
    ```shell
    pnpm install
    ```
+4. Optionally, verify that everything is working correctly:
+   ```shell
+   pnpm check
+   pnpm test
+   ```
+
+## Making changes
 
-## Making Changes
+Create a new branch for your changes
 
-### Implement Your Changes
+```shell
+git checkout -b my-branch
+```
 
 Make the changes you propose to the codebase. If your changes impact functionality, please **add corresponding tests**
 to validate your updates.
 
-### Validate Your Changes
+### Validate your changes
 
 Run the following commands to ensure your changes do not introduce any issues:
 
@@ -38,9 +55,7 @@ Run the following commands to ensure your changes do not introduce any issues:
     - If you encounter style issues, use `pnpm lint-fix` to automatically correct some of these.
 - `pnpm dtslint`: Run type-level tests.
 
-### Document Your Changes
-
-**Changeset Documentation**
+### Document your changes
 
 Before committing your changes, document them with a changeset. This process helps in tracking modifications and
 effectively communicating them to the project team and users:
@@ -56,44 +71,95 @@ During the changeset creation process, you will be prompted to select the approp
 - **minor**: Choose this for new features that enhance functionality but do not disrupt existing features.
 - **major**: Select this for any changes that result in backward-incompatible modifications to the library.
 
-## Finalizing Your Contribution
+### Commit your changes
 
-### Commit Your Changes
-
-Once you have documented your changes with a changeset, it’s time to commit them to the repository. Use a clear and
-descriptive commit message, which could be the same message you used in your changeset:
+Once you have documented your changes, commit them to the repository:
 
 ```bash
-git commit -am 'Add some feature'
+git commit -am "Add some feature"
 ```
 
-#### Linking to Issues
+#### Linking to issues
 
 If your commit addresses an open issue, reference the issue number directly in your commit message. This helps to link
-your contribution clearly to specific tasks or bug reports. Additionally, if your commit resolves the issue, you can
-indicate this by adding a phrase like `", closes #<issue-number>"`. For example:
+your contribution clearly to specific tasks or bug reports.
+
+For example:
 
 ```bash
-git commit -am 'Add some feature, closes #123'
-```
+# Reference issue #123
+git commit -am "Add some feature (#123)"
 
-This practice not only helps in tracking the progress of issues but also automatically closes the issue when the commit
-is merged, streamlining project management.
+# Close the issue #123
+git commit -am "Add some feature (close #123)"
+```
 
-### Push to Your Fork
+### Push to your fork
 
-Push the changes up to your GitHub fork:
+Push the changes to your GitHub fork:
 
 ```bash
 git push origin my-branch
 ```
 
-### Create a Pull Request
+### Create a pull request
 
 Open a pull request against the main branch on the original repository.
 
 Please be patient! We will do our best to review your pull request as soon as possible.
 
-## Release a new version (for maintainers)
+## Tests
+
+We use [@testcontainers/mongodb](https://node.testcontainers.org/modules/mongodb/) to run MongoDB in a Docker container
+during tests.
 
-Merge the PRs automatically created on GitHub with the name "Version Packages".
+### Write a test
+
+In the `test` directory of a package, like [packages/effect-mongodb/test](packages/effect-mongodb/test), create a
+new file `<test suite name>.test.ts`.
+
+Use the `describeMongo` function to automatically setup your test suite with a MongoDB connection.
+
+```typescript
+import * as Db from "effect-mongodb/Db"
+import * as DocumentCollection from "effect-mongodb/DocumentCollection"
+import * as Effect from "effect/Effect"
+import * as O from "effect/Option"
+import { ObjectId } from "mongodb"
+import { expect, test } from "vitest"
+import { describeMongo } from "./support/describe-mongo.js"
+
+describeMongo("My tests", (ctx) => {
+  test("find one", async () => {
+    const program = Effect.gen(function* (_) {
+      const db = yield* _(ctx.database)
+      const collection = Db.documentCollection(db, "find-one")
+
+      yield* _(
+        DocumentCollection.insertMany(collection, [{ name: "john" }, { name: "alfred" }])
+      )
+
+      return yield* _(DocumentCollection.findOne(collection, { name: "john" }))
+    })
+
+    const result = await Effect.runPromise(program)
+
+    expect(result).toEqual(O.some({ _id: expect.any(ObjectId), name: "john" }))
+  })
+})
+```
+
+### Inspect MongoDB test instance
+
+1. Export `EFFECT_MONGODB_DEBUG=true` environment variable
+2. Run the tests (by default in watch mode) and you will see the connection string in the console output
+   ```
+   [EFFECT_MONGODB_DEBUG] MongoDB connection string with direct connection: 'mongodb://localhost:32775'
+   ```
+3. Copy the connection string `mongodb://localhost:32775`
+4. Open [MongoDB Compass](https://www.mongodb.com/products/tools/compass)
+5. Click **Add new connection**
+6. Paste the copied connection string in the URI field
+7. Click Advanced Connection Options
+8. Enable **Direct Connection**
+9. Click **Save & Connect**

RELEASE.md

@@ -0,0 +1,7 @@
+# Release
+
+This is a guide for maintainers on how to release a new version of the library.
+
+## Release a new version
+
+Merge the Pull Request automatically created on GitHub with the name **Version Packages** by changeset bot.