feat(docs): add contribution usage examples and other useful information

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing Guide
+
+Thank you for your interest in contributing! This repository hosts versioned PHP Docker images with optional NVM and Node.js support.
+
+## 📋 Contribution Checklist
+
+Before opening a Pull Request, please make sure that:
+
+- You are modifying or adding files in the correct version folder (e.g. `8.3/Dockerfile`)
+- Your PR **title follows the [Conventional Commits](https://www.conventionalcommits.org/) format** and includes a valid **scope**
+    - ✅ Correct examples:
+        - `feat(8.4): add support for PHP 8.4`
+        - `fix(8.3): correct NVM install path`
+        - `chore(8.3): update nvm version`
+    - ❌ Invalid examples (missing scope or wrong format):
+        - `feat: add PHP 8.4` ← missing scope
+        - `fix php 8.3 image` ← not a conventional commit format
+
+> The `scope` must describe the context of the change, such as the PHP version (`8.0`, `8.3`, etc.) or a general target like `docker` or `ci`.
+
+- Your Dockerfile change builds successfully
+    - The GitHub workflow will attempt to build the image automatically
+    - You can also test locally with:
+      ```sh
+      docker build -t php-custom:8.3 ./8.3
+      ```
+
+## ✅ Best Practices
+
+- **Avoid modifying multiple PHP versions in a single PR** unless necessary
+- Keep version-specific differences minimal and well-documented in `README.md` if needed
+- If adding a new PHP version (e.g. `8.4`), use the closest previous version (e.g. `8.3`) as a starting point
+
+## 🧪 CI Workflow
+
+All PRs trigger a GitHub Actions workflow which will:
+
+- Validate the PR title against Conventional Commits with required scope
+- Build the updated Docker image to ensure it compiles successfully
+
+After a successful squash merge a GitHub Actions workflow will publish the new versions to Docker Hub.
+
+You can find the workflow definitions at [.github/workflows](.github/workflows).
+
+## 🛡️ Security
+
+If you're introducing or updating external binaries (e.g. Node.js, NVM), use official sources and verify integrity (e.g. via checksum or GPG).
+
+If you're unsure about anything, feel free to open a draft PR or discussion.

README.md

@@ -1,14 +1,74 @@
 # php-nvm
 
-🐳 Generic docker image for PHP applications that contains nvm for handling multiple Node.js versions dynamically
+🐳 **php-nvm** is a generic, lightweight Docker image for PHP applications that includes [NVM](https://github.com/nvm-sh/nvm), allowing dynamic management of multiple Node.js versions at runtime.
 
-[![Docker Badge](https://img.shields.io/docker/pulls/ocreaper/php-nvm)](https://hub.docker.com/r/ocreaper/php-nvm/) ![Static Badge](https://img.shields.io/badge/nvm-v0.40.3-blue)
+[![Docker Pulls](https://img.shields.io/docker/pulls/ocreaper/php-nvm)](https://hub.docker.com/r/ocreaper/php-nvm/)
+![NVM Version](https://img.shields.io/badge/nvm-v0.40.3-blue)
 
+---
 
-| Tags | PHP version | Features |
-|------|-------------| - |
-| 8.0  | 8.0         | ✅ Everything. |
-| 8.1  | 8.1         | ✅ Everything. |
-| 8.2  | 8.2         | ✅ Everything. |
-| 8.3  | 8.3         | ✅ Everything. |
-| 8.4  | 8.4         | ✅ Everything. |
+## 🚀 Features
+
+- ✅ PHP 8.x support (8.0–8.4)
+- ✅ Pre-installed [NVM](https://github.com/nvm-sh/nvm) for managing multiple Node.js versions
+- ✅ Ideal for modern full-stack PHP projects that require Node.js tooling (e.g. Webpack, Vite, etc.)
+- ✅ CI-friendly: small, clean, and consistently versioned
+- ✅ Useful system tools: `git`, `rsync`, `openssh-client`, `make`, `curl`, etc.
+- ✅ All images share the same consistent build logic
+
+---
+
+## 📦 Available Tags
+
+| Tag  | PHP Version | Included Tools                         |
+|------|-------------|----------------------------------------|
+| 8.0  | 8.0         | ✅ PHP, Composer, NVM, Node.js via NVM |
+| 8.1  | 8.1         | ✅ PHP, Composer, NVM, Node.js via NVM |
+| 8.2  | 8.2         | ✅ PHP, Composer, NVM, Node.js via NVM |
+| 8.3  | 8.3         | ✅ PHP, Composer, NVM, Node.js via NVM |
+| 8.4  | 8.4         | ✅ PHP, Composer, NVM, Node.js via NVM |
+
+> ℹ️ The exact Node.js version is not preinstalled — use `nvm install` as needed in your Dockerfile or entrypoint script.
+
+---
+
+## 🧪 Usage
+
+### 🐋 Example Dockerfile
+
+```Dockerfile
+FROM ocreaper/php-nvm:8.3
+
+# Install Node.js 18 using NVM
+RUN source ~/.nvm/nvm.sh && \
+    nvm install 18 && \
+    nvm use 18 && \
+    node -v && npm -v
+
+# Set up your app
+COPY . /app
+WORKDIR /app
+RUN composer install
+```
+
+### 💻 Run it interactively
+
+```sh
+docker run -it --rm ocreaper/php-nvm:8.3 bash
+```
+
+## 🤝 Contributing
+
+Any contributions are welcomed!
+
+Use Conventional Commits with a required scope:
+
+- ✅ feat(8.4): add PHP 8.4 support
+- ✅ fix(8.3): correct NVM installation path
+
+GitHub Actions will:
+
+- ✅ Enforce PR title formatting
+- ✅ Ensure the Docker image builds successfully
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full contribution guidelines.