diff --git a/.gitignore b/.gitignore index 58b4c86..7f36478 100644 --- a/.gitignore +++ b/.gitignore @@ -14,7 +14,9 @@ !go.sum !go.mod +!CONTRIBUTING.md !README.md +!SECURITY.md !LICENSE # ...also in subdirectories diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a333e42 --- /dev/null +++ b/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 +``` diff --git a/README.md b/README.md index 4b388b5..66f3730 100644 --- a/README.md +++ b/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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e16fc97 --- /dev/null +++ b/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.