chore: standardize contributing guide across org

Author: clairevnext

CONTRIBUTING.md

@@ -1,121 +1,118 @@
-# Contributing to `list`
+# Contributing
 
-Thanks for your interest in contributing. This guide covers the operational process. For the **why** — the design principles every contribution is tested against — see **[bold-minds/oss/PRINCIPLES.md](https://github.com/bold-minds/oss/blob/main/PRINCIPLES.md)**.
+Thank you for your interest in contributing! We welcome contributions that improve the library while maintaining its focus on simplicity, performance, and Go idioms.
 
-## 🎯 Before You Start
+## Getting Started
 
-Every contribution is measured against the four Bold Minds principles: **outcome naming**, **one way to do each thing**, **get out of the way**, and **non-goals explicit**. If your proposed change doesn't honor these, it will not be merged.
+### Prerequisites
 
-**Read [PRINCIPLES.md](https://github.com/bold-minds/oss/blob/main/PRINCIPLES.md) first.** It's the load-bearing document.
+- **Go 1.22+**
+- **Git**
+- **golangci-lint** (optional, for comprehensive linting)
 
-## 🔧 Development Setup
+### Development Setup
 
-**Requirements:** Go 1.23 or later, Git, Bash.
+1. **Fork and clone the repository**:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/list.git
+   cd list
+   ```
 
-```bash
-git clone https://github.com/bold-minds/list.git
-cd list
-go test ./...              # unit tests
-go test -race ./...        # race detection
-go test -bench=. ./...     # benchmarks
-./scripts/validate.sh      # full validation pipeline (local mode)
-./scripts/validate.sh ci   # strict CI mode
-```
+2. **Run tests**:
+   ```bash
+   go test -race ./...
+   ```
 
-Your contribution must pass `./scripts/validate.sh ci` before submitting.
+## What We're Looking For
 
-## 📁 Project Structure
+### Encouraged
 
-```
-list/
-├── list.go                # Implementation (single file)
-├── list_test.go           # Unit tests
-├── bench_test.go          # Benchmarks
-├── examples/              # Runnable examples
-├── scripts/
-│   └── validate.sh        # Validation pipeline
-├── README.md
-├── CONTRIBUTING.md        # This file
-├── CHANGELOG.md
-├── CODE_OF_CONDUCT.md
-├── SECURITY.md
-├── LICENSE
-└── go.mod
-```
+- **Bug fixes** — fix issues or edge cases
+- **Performance improvements** — optimize without breaking compatibility
+- **Test enhancements** — add test cases, improve coverage
+- **Documentation improvements** — clarify usage, add examples
 
-Flat layout. No `internal/` directory.
+### Requires Discussion First
 
-## 🎨 Code Style
+- **API changes** — modifications to public interfaces
+- **New dependencies** — adding external packages
+- **Breaking changes** — changes that affect backward compatibility
 
-### Naming
-- Outcome naming per PRINCIPLES.md. Function names describe the set operation performed (`Unique`, `Union`, `Intersect`, `Minus`, `Without`).
+### Not Accepted
 
-### Error Handling
-- Functions **must not panic** on valid input (nil, empty, or otherwise).
-- No error returns — set operations either succeed or return empty slices.
-- Never `Must*` variants.
+- **Feature creep** — complex features that don't align with Go idioms
+- **Non-idiomatic Go** — code that doesn't follow Go conventions
+- **Performance regressions** — changes that significantly slow down the library
 
-### Documentation
-- Every exported function has a doc comment.
-- Edge cases (nil, empty, NaN, aliasing, immutability) documented in the package doc and README.
+## Contribution Process
 
-### Dependencies
-- **Zero external dependencies.** `list` is pure stdlib.
+### 1. Create an Issue First
 
-## 🧪 Testing
+For significant changes, please create an issue to discuss:
+- What problem you're solving
+- Your proposed approach
+- Any potential breaking changes
 
-**Coverage target: 100% of exported functions.**
+### 2. Development Workflow
 
-```bash
-go test -v ./...
-go test -race ./...
-go test -cover ./...
-go test -bench=. -benchmem ./...
-```
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
 
-**Every PR must include adversarial tests.** In addition to happy-path coverage, tests must verify:
+2. **Make your changes** — follow the code style guidelines below, add tests, update documentation as needed.
 
-1. **Non-nil empty returns** — no function returns nil for empty or missing results.
-2. **Immutability** — the input slice is byte-identical before and after the call.
-3. **Result aliasing** — mutating the returned slice must not affect the input.
-4. **NaN semantics** (for float-aware features) — behavior is consistent with Go's map-key rules.
-5. **Custom comparable types** — named types (`type UserID string`) and struct keys work correctly.
+3. **Validate your changes**:
+   ```bash
+   go fmt ./...
+   go vet ./...
+   go test -race ./...
+   ```
 
-## 📝 Pull Request Process
+4. **Commit your changes**:
+   ```bash
+   git commit -m "feat: add your feature description"
+   ```
 
-### PR Checklist
+5. **Push and create a pull request**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
 
-- [ ] **Outcome naming** — does the function name describe what the caller gets?
-- [ ] **One way** — does any existing function already do this?
-- [ ] **Get out of the way** — can a Go dev use this from the signature alone?
-- [ ] **Non-goals** — does this violate any of the library's stated non-goals?
-- [ ] Tests cover 100% of new code
-- [ ] Adversarial tests included (nil, immutability, aliasing, NaN where applicable)
-- [ ] Benchmarks added for new exported functions
-- [ ] README updated
-- [ ] CHANGELOG.md updated
-- [ ] `./scripts/validate.sh ci` passes locally
+### 3. Pull Request Guidelines
 
-## 🆕 Adding a New Function
+Your PR should:
+- Have a clear title describing the change
+- Reference any related issues using `Fixes #123` or `Closes #123`
+- Include tests for new functionality
+- Pass all CI checks
+- Maintain backward compatibility unless discussed otherwise
 
-`list` is deliberately tiny (five functions). New additions must clear a high bar:
+## Code Style
 
-1. Read the library's non-goals in [README.md](README.md) and [PRINCIPLES.md](https://github.com/bold-minds/oss/blob/main/PRINCIPLES.md).
-2. Prove the stdlib gap. Current Go's `slices` package is more capable than many people realize.
-3. Show real-world evidence of the pain.
-4. If the function operates on maps or uses a predicate, it belongs in a different library (`each` for predicates, `stdlib maps` for maps).
+- Follow standard Go formatting (`go fmt`)
+- Use meaningful variable and function names
+- Write clear, concise comments for public APIs
+- Follow Go's error handling patterns
+- Write table-driven tests where appropriate
+- Test both success and error cases
+- Include edge cases (nil values, empty strings, etc.)
+- Run tests with `-race` to ensure thread safety
 
-## 🏷️ Versioning and Releases
+## Commit Messages
+
+We follow conventional commits:
+
+```
+type(scope): description
+```
 
-- Semantic versioning
-- v0.x: API may change between minor versions
-- v1.0+: breaking changes require major version bump
-- Every release updates CHANGELOG.md
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`
 
-## 🙏 Code of Conduct
+## Code Review
 
-See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+We look for: correctness, performance, style, tests, documentation, and backward compatibility. Initial review within 2-3 business days.
 
-## 📄 License
+## License
 
-By contributing, you agree your contributions are licensed under the MIT License.
+By contributing, you agree that your contributions will be licensed under the same license that covers the project.