docs: Update README

CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing
+
+Thanks for considering a contribution to `bash-helpers`.
+
+## Before you start
+
+- Check [open issues](https://github.com/nafigator/bash-helpers/issues) and [pull requests](https://github.com/nafigator/bash-helpers/pulls) — maybe the topic is already discussed.
+- For significant changes, open an issue first to agree on the approach.
+- For security issues, do **not** open a public issue. See [SECURITY.md](SECURITY.md).
+
+## Requirements
+
+- Bash 3.2+ (target environment — see README → Dependencies).
+- [`shellcheck`](https://www.shellcheck.net/) for static analysis.
+- `git` with commit signing optional.
+
+## Development setup
+
+```bash
+git clone https://github.com/nafigator/bash-helpers.git
+cd bash-helpers
+```
+
+The library is a single file: `src/bash-helpers.sh`. There is no build step.
+
+To test your changes locally:
+
+```bash
+bash -n src/bash-helpers.sh
+shellcheck src/bash-helpers.sh
+```
+
+To try the library in a sandbox script:
+
+```bash
+cat > /tmp/try.sh <<'EOF'
+#!/usr/bin/env bash
+. "$PWD/src/bash-helpers.sh"
+inform 'works'
+EOF
+bash /tmp/try.sh
+```
+
+## Coding guidelines
+
+- Target **Bash 3.2+**. Do not use bash 4.x-only features (associative arrays, `mapfile`, `${var,,}`, `coproc`) unless the project bumps the minimum version.
+- Keep functions **small and single-purpose**.
+- Use `local` for variables inside functions. Prefer `local -r` for constants.
+- Quote expansions: `"$var"`, `"${arr[@]}"`.
+- Prefer `[[ ]]` over `[ ]` in conditionals.
+- Prefer `printf` over `echo` for anything non-trivial.
+- Return meaningful exit codes: `0` — success, non-zero — failure.
+- Do not break existing public function signatures. README declares all function signatures as public API (see Versioning).
+- Keep user-facing messages in English.
+- Avoid new external dependencies. If a new dependency is unavoidable, document it in README → Dependencies.
+
+## Style
+
+- Indentation: **tabs** (matches the current file).
+- Function naming: `lower_snake_case`, public helpers without a prefix.
+- Comments: explain *why*, not *what*. Keep them short.
+- No trailing whitespace, file ends with a single newline.
+
+## Commits
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <short summary>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Common types:
+
+| Type | When |
+|------|------|
+| `feat` | New function or new capability of an existing function |
+| `fix`  | Bug fix |
+| `docs` | README, comments, examples |
+| `refactor` | Internal change without behavior change |
+| `test` | Tests and CI |
+| `chore` | Tooling, configs, version bumps |
+
+Examples:
+
+```
+feat(status): accept OK/FAIL aliases in addition to codes
+fix(float): handle empty and '""' input
+docs(readme): document BASH_HELPERS_VERSION
+```
+
+Rules:
+
+- One logical change per commit.
+- Summary in imperative mood, lowercase, no trailing period.
+- Keep the subject under ~72 characters.
+- Reference issues in the footer: `Closes #42`.
+
+## Pull requests
+
+1. Fork the repo and create a topic branch from `main`:
+   ```bash
+   git checkout -b feat/my-change
+   ```
+2. Make your change. Keep the diff focused.
+3. Run `bash -n` and `shellcheck` on the file — CI will run them too.
+4. Update README if you add/change/remove a public function, dependency, or configuration variable.
+5. Commit using Conventional Commits.
+6. Push and open a PR against `main`. Fill in the description: what, why, how to test.
+7. Link related issues.
+
+PR checklist:
+
+- [ ] `bash -n src/bash-helpers.sh` passes
+- [ ] `shellcheck src/bash-helpers.sh` passes
+- [ ] New/changed functions documented in README
+- [ ] No new external dependencies (or documented)
+- [ ] Public signatures unchanged, or breaking change explicitly noted
+- [ ] Commit messages follow Conventional Commits
+
+## Review process
+
+- Maintainers review within a few days.
+- Address review comments with new commits (do not force-push during review unless asked).
+- Once approved, the PR is squash-merged or merged with a merge commit — maintainer's choice.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE).

README.md

@@ -4,6 +4,8 @@
 
 **Collection of useful functions for usage in Bash scripts**
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
+
 ## Usage
 
 <details>
@@ -12,7 +14,7 @@
 ```bash
 #!/usr/bin/env bash
 
-source <(curl -s https://raw.githubusercontent.com/nafigator/bash-helpers/1.1.4/src/bash-helpers.sh)
+source <(curl -s https://raw.githubusercontent.com/nafigator/bash-helpers/1.1.5/src/bash-helpers.sh)
 
 inform 'Bash helpers ready!'
 ```
@@ -159,6 +161,118 @@ composer require nafigator/bash-helpers
 	```
 	![Debug messages][Debug messages img]
 
+## Configuration
+
+The library is configured via environment variables and by overriding a few functions.
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `INTERACTIVE` | `1` if stdin and stdout are TTY, otherwise empty | Enables ANSI color output. Set to empty (`INTERACTIVE=`) to disable colors (e.g. for logs). |
+| `DEBUG` | unset | Enables `debug()` and `status_dbg()` output. Set to any non-empty value (e.g. `DEBUG=1`). |
+| `VERSION` | unset | Your script version. Used by `print_version()`. Define it in your main script. |
+
+Examples:
+
+```bash
+# Redefine to disable colors
+INTERACTIVE=
+
+# Redefine to enable debug output
+DEBUG=1
+
+# Redefine version in your script for print_version
+VERSION=1.2.3
+```
+
+### Overriding functions
+
+Two functions are meant to be redefined in your script to match your CLI:
+
+- `usage_help()` — prints help text. Redefine to show your own options.
+- `print_version()` — prints version. Redefine if you need custom output (it uses `$VERSION` and `$BASH_HELPERS_VERSION` by default).
+- `parse_options()` — parses options. Redefine if you have extended set of options.
+
+Example:
+
+```bash
+usage_help() {
+  echo "Usage: my-script [OPTIONS]"
+  echo "  -v, --version  Show version"
+  echo "  -h, --help     Show this help"
+}
+
+print_version() {
+  echo "my-script $VERSION"
+}
+```
+
+### Include directory
+
+`include()` loads files from a fixed path:
+
+```bash
+/usr/local/lib/bash/includes
+```
+
+If you need a different location, redefine `include()` in your script.
+
+### Notes
+
+- `INTERACTIVE` and `DEBUG` are read at call time, so you can change them during script execution.
+- `VERSION` must be set before calling `print_version()`.
+- Color functions (`red`, `bold`, etc.) respect `INTERACTIVE` automatically.
+
+## Dependencies
+
+### Required
+
+| Dependency | Version | Purpose                                                                                                                                |
+|------------|---------|----------------------------------------------------------------------------------------------------------------------------------------|
+| `bash`     | ≥ 3.2   | local -r, printf, [[ ]], getopts and other 3.x features used across helpers                                                            |
+| `POSIX utilities`| —       | `printf`, `date`, `readlink`, `basename` — used by `format_date`, `inform`, `warning`, `error`, `debug`, `usage_help`, `print_version` |
+
+### Optional
+
+Installed only if you use the corresponding function.
+
+| Dependency | Used by | Purpose |
+|------------|---------|---------|
+| `bc`       | `float()` | Arbitrary precision arithmetic for decimal conversion |
+| `sed`      | `float()` | Normalizes decimal separator (`,` → `.`) |
+| `git`      | `git_config_bool()` | Reads boolean values from git config |
+| `curl`     | Installation snippets in this README | Downloads `bash-helpers.sh` |
+
+### Function → dependency map
+
+| Function | Depends on                     |
+|----------|--------------------------------|
+| `black` … `clr` | `printf` (builtin)             |
+| `format_date` | `date`, `printf` (builtin)     |
+| `error`, `inform`, `warning`, `debug` | `date`, `printf` (builtin)     |
+| `status`, `status_dbg` | `date`, `printf` (builtin)     |
+| `check_dependencies` | `date`, `command -v` (builtin) |
+| `float` | `sed`, `bc`                    |
+| `include` | — (pure bash)                  |
+| `usage_help`, `print_version` | `basename`, `readlink`         |
+| `git_config_bool` | `git`                          |
+| `parse_options` | `getopts` (builtin)            |
+
+### Checking at runtime
+
+Use the bundled helper to verify dependencies before running your script:
+
+```bash
+check_dependencies bash date git || exit 1
+```
+
+### Notes
+
+- All helpers assume a POSIX-like environment (Linux, macOS, BSD). Windows is supported only via WSL or MSYS2/Cygwin.
+- `bc` is not installed by default on minimal images (e.g. `alpine`, `debian:slim`). Install it with `apk add bc` / `apt-get install -y bc` if you rely on `float()`.
+- `INTERACTIVE` and `DEBUG` are **not** external dependencies — they are environment variables consumed by the library. See [Configuration](#configuration)
+
 ## Message statuses
 
 	[ OK ] - success status

composer.json

@@ -3,7 +3,7 @@
     "description": "Collections of useful functions for usage in Bash scripts.",
     "type": "library",
     "license": "MIT",
-    "version": "1.1.4",
+    "version": "1.1.5",
     "authors": [{
         "name": "Yancharuk Alexander",
         "role": "developer"

src/bash-helpers.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-#Copyright (c) 2017-2025 Yancharuk Alexander
+#Copyright (c) 2017-2026 Yancharuk Alexander
 #
 #Permission is hereby granted, free of charge, to any person obtaining a copy
 #of this software and associated documentation files (the "Software"), to deal
@@ -21,7 +21,7 @@
 #SOFTWARE.
 
 # shellcheck disable=SC2034
-BASH_HELPERS_VERSION=1.1.4
+BASH_HELPERS_VERSION=1.1.5
 
 INTERACTIVE=$([[ -t 0 && -t 1 ]] && echo 1)
 DEBUG=