Improve docs

.gitignore

@@ -14,7 +14,9 @@
 !go.sum
 !go.mod
 
+!CONTRIBUTING.md
 !README.md
+!SECURITY.md
 !LICENSE
 
 # ...also in subdirectories

CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to sortof
+
+Thank you for your interest in **sortof**! Contributions are welcome from everyone, no matter your experience level with programming or open source.
+
+By contributing, you agree that your work will be licensed under the same terms as the rest of the project (see [LICENSE](./LICENSE) for details).
+
+By following these guidelines, you’ll benefit from:
+
+- smoother collaboration and less back-and-forth
+- faster reviews and merges
+- opportunities to learn Go best practices, testing, and open source workflows.
+
+## Ways to contribute
+
+### For everyone
+
+- Ask **questions** about algorithms or code in [discussions](https://github.com/macie/sortof/discussions)
+- Report **bugs** using _[Bug report](https://github.com/macie/sortof/issues)_ issue template
+- Suggest **new algorithms** (even without implementation) with _[Feature suggestion](https://github.com/macie/sortof/issues)_ issue template
+- Participate in **discussions** to help others
+- Create **examples** demonstrating the library or CLI usage
+- Fix **typos** in documentation and code comments (see below)
+- Test on **different OSes** and report any issues
+- Improve **documentation** for clarity and completeness (see below)
+- Help **organize issues** by labeling and triaging bug reports
+
+### For programmers
+
+- Fix **bugs** in existing implementations
+- Write additional **tests** to improve coverage
+- Expand **platform support** for different operating systems
+- Implement **new sorting algorithms** (see detailed guide below)
+
+When reporting **build issues**, include `make info` output with your report.
+
+If you're looking for a place to start, check issues labeled `good first issue` or `help wanted`.
+
+## Small improvements
+
+For **typo fixes** or **documentation improvements**:
+
+1. Edit the file directly on GitHub (click the pencil icon)
+2. Describe your changes in the commit message
+3. Create a pull request
+
+## Code changes
+
+Before contributing code, you'll need:
+
+- `git` - for version control ([cheat sheet](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics))
+- `go` - the programming language ([installation](https://go.dev/doc/install))
+- `make` - for running build commands (usually pre-installed on Linux/macOS), such as:
+    - `make check` - runs code quality checks (formatting, linting)
+    - `make test` - runs unit tests for all algorithms
+    - `make e2e` - runs end-to-end tests (tests the CLI tool)
+    - `make info` - shows system and build information
+
+For **bug fixes** or **small improvements** use the standard GitHub workflow:
+
+1. Fork and clone the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes
+4. Test: `make check && make test && make e2e`
+5. Commit and submit a pull request
+
+### Adding a new sorting algorithm
+
+Each PR with a new algorithm must include:
+
+1. A new `{algorithm}.go` file with implementation:
+
+    ```go
+    func {Algorithm}[T constraints.Ordered](ctx context.Context, data []T) error {
+        // implementation must support context cancellation (check ctx.Done() periodically)
+    }
+    ```
+
+2. A new `{algorithm}_test.go` file with tests (see `bogosort_test.go` as example)
+
+3. Changes to `cmd/sortof/cli.go` file (to enable the algorithm in the CLI tool)
+
+4. Updates to the `Makefile` file (to add E2E tests for the new algorithm)
+
+5. Updates to the `README.md` file (with a brief description of the new algorithm)
+
+#### Quality requirements
+
+Use this PR template as a checklist:
+
+```markdown
+## Description
+
+Brief algorithm description and motivation:
+
+- **Complexity**: O(?)
+- **Unique behavior**: What makes it interesting?
+
+## Checklist
+
+- [ ] Algorithm implementation with context support
+- [ ] Comprehensive tests (various inputs, edge cases, cancellation)
+- [ ] CLI integration added (`cmd/sortof/cli.go`)
+- [ ] E2E CLI tests added (`Makefile`)
+- [ ] `README.md` updated
+```

README.md

@@ -12,10 +12,13 @@
 
 Implemented algorithms:
 
-- [bogosort](https://en.wikipedia.org/wiki/Bogosort)
-- [miraclesort](https://en.wikipedia.org/wiki/Bogosort#miracle_sort)
-- [slowsort](https://en.wikipedia.org/wiki/Slowsort)
-- [stalinsort](https://mastodon.social/@mathew/100958177234287431).
+- impractical due to poor time complexity:
+    - [bogosort](https://en.wikipedia.org/wiki/Bogosort)
+    - [miraclesort](https://en.wikipedia.org/wiki/Bogosort#miracle_sort)
+    - [slowsort](https://en.wikipedia.org/wiki/Slowsort)
+
+- impractical due to destructive behavior:
+    - [stalinsort](https://mastodon.social/@mathew/100958177234287431)
 
 ## Usage
 
@@ -32,35 +35,37 @@ c
 
 ## Installation
 
-Download [latest stable release from GitHub](https://github.com/macie/sortof/releases/latest) .
+Download the [latest stable release from GitHub](https://github.com/macie/sortof/releases/latest).
 
-You can also build it manually with commands: `make && make build`.
+You can also build it manually with: `make && make build`.
 
 ## Development
 
+For detailed contribution guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 Use `make` (GNU or BSD):
 
 - `make` - install dependencies
-- `make test` - runs test
-- `make e2e` - runs e2e tests for CLI
-- `make check` - static code analysis
+- `make test` - run tests
+- `make e2e` - run end-to-end tests for CLI
+- `make check` - run static code analysis
 - `make build` - compile binaries from latest commit
 - `make dist` - compile binaries from latest commit for supported OSes
-- `make clean` - removes compilation artifacts
+- `make clean` - remove compilation artifacts
 - `make cli-release` - tag latest commit as a new release of CLI
 - `make module-release` - tag latest commit as a new release of Go module
 - `make info` - print system info (useful for debugging).
 
 ### Versioning
 
-The repo contains CLI and Go module which can be developed with different pace.
+This repository contains both a CLI and Go module which can be developed at different paces.
 Commits with versions are tagged with:
 - `vX.X.X` (_[semantic versioning](https://semver.org/)_) - versions of Go module
 - `cli/vYYYY.0M.MICRO` (_[calendar versioning](https://calver.org/)_) - versions of command-line utility.
 
 ### Security hardening
 
-On modern Linuxes and OpenBSD, CLI application has restricted access to kernel
+On modern Linux distributions and OpenBSD, the CLI application has restricted access to kernel
 calls with [seccomp](https://en.wikipedia.org/wiki/Seccomp) and [pledge](https://man.openbsd.org/pledge.2).
 
 ## License

SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+**Full disclosure** via [GitHub Issues](https://github.com/macie/sortof/issues) is the preferred approach for this project. It allows all users to respond promptly to reported vulnerabilities.
+
+If you prefer a **coordinated disclosure** process, please use the [GitHub Security Advisories form](https://github.com/macie/sortof/security/advisories/new).
+
+Due to limited contributor pool and resources, addressing reported vulnerabilities may take up to 90 days.