📝 Add README, EXAMPLES.md & CONTRIBUTING.md

Author: geekloper

CONTRIBUTING.md

@@ -0,0 +1,294 @@
+# Contributing to Zut
+
+Thank you for your interest in contributing to Zut! This document provides guidelines and instructions for contributing.
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.23.6 or higher
+- Git
+
+### Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/yourusername/zut.git
+   cd zut
+   ```
+
+3. Install dependencies:
+   ```bash
+   go mod download
+   ```
+
+4. Build the project:
+   ```bash
+   make build
+   # or
+   go build -o zut .
+   ```
+
+5. Run tests:
+   ```bash
+   make test
+   # or
+   go test ./...
+   ```
+
+## Project Structure
+
+```
+zut/
+├── cmd/                # CLI command implementations
+│   ├── root.go        # Root command and CLI setup
+│   ├── add.go         # Add command
+│   ├── list.go        # List command
+│   ├── delete.go      # Delete command
+│   ├── edit.go        # Edit command
+│   ├── run.go         # Run command
+│   └── find.go        # Find/search command
+├── internal/core/     # Core business logic
+│   ├── core.go        # Command management
+│   └── core_test.go   # Core tests
+├── pkg/storage/       # Data persistence layer
+│   ├── storage.go     # Storage implementation
+│   └── storage_test.go # Storage tests
+├── main.go            # Application entry point
+├── go.mod             # Go module definition
+├── Makefile           # Build automation
+├── README.md          # Main documentation
+├── ROADMAP.md         # Project roadmap
+├── EXAMPLES.md        # Usage examples
+└── CONTRIBUTING.md    # This file
+```
+
+## Development Workflow
+
+### Making Changes
+
+1. Create a new branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes
+
+3. Run tests:
+   ```bash
+   make test
+   ```
+
+4. Format your code:
+   ```bash
+   make fmt
+   ```
+
+5. Commit your changes:
+   ```bash
+   git commit -am "Add feature: description"
+   ```
+
+6. Push to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. Create a Pull Request
+
+### Commit Message Guidelines
+
+- Use present tense ("Add feature" not "Added feature")
+- Use imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Start with a capital letter
+- Keep first line under 72 characters
+- Reference issues and pull requests when relevant
+
+Examples:
+```
+Add search functionality to list command
+Fix bug in command deletion
+Update README with installation instructions
+Refactor storage layer for better error handling
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run tests with coverage
+make test-coverage
+
+# Run tests verbosely
+go test ./... -v
+
+# Run specific package tests
+go test ./pkg/storage -v
+go test ./internal/core -v
+```
+
+### Writing Tests
+
+- Place test files next to the code they test (e.g., `storage.go` → `storage_test.go`)
+- Use table-driven tests when testing multiple scenarios
+- Use meaningful test names that describe what is being tested
+- Test both success and error cases
+- Aim for high test coverage (>80%)
+
+Example test structure:
+```go
+func TestFeatureName(t *testing.T) {
+    // Setup
+    manager := setupTestManager(t)
+    
+    // Execute
+    err := manager.SomeMethod()
+    
+    // Verify
+    if err != nil {
+        t.Fatalf("SomeMethod() failed: %v", err)
+    }
+}
+```
+
+## Code Style
+
+### Go Conventions
+
+- Follow standard Go formatting (use `gofmt` or `make fmt`)
+- Use meaningful variable and function names
+- Keep functions small and focused
+- Add comments for exported functions and types
+- Handle errors appropriately
+- Use `go vet` to catch common mistakes
+
+### Package Organization
+
+- `cmd/` - CLI command implementations (uses Cobra)
+- `internal/core/` - Business logic (should not import cmd/)
+- `pkg/storage/` - Reusable storage utilities
+
+### Error Handling
+
+```go
+// Good: Wrap errors with context
+if err := doSomething(); err != nil {
+    return fmt.Errorf("failed to do something: %w", err)
+}
+
+// Good: Check errors immediately
+result, err := fetchData()
+if err != nil {
+    return err
+}
+
+// Bad: Ignoring errors
+result, _ := fetchData()
+```
+
+## Adding New Features
+
+### Adding a New Command
+
+1. Create a new file in `cmd/` (e.g., `cmd/newcommand.go`)
+2. Implement the command using Cobra:
+   ```go
+   func NewMyCommand() *cobra.Command {
+       cmd := &cobra.Command{
+           Use:   "mycommand",
+           Short: "Brief description",
+           Long:  "Detailed description",
+           RunE: func(cmd *cobra.Command, args []string) error {
+               // Implementation
+               return nil
+           },
+       }
+       return cmd
+   }
+   ```
+
+3. Register the command in `cmd/root.go`:
+   ```go
+   cmd.AddCommand(NewMyCommand())
+   ```
+
+4. Add tests in `cmd/` if needed
+5. Update README.md with usage examples
+
+### Adding Core Functionality
+
+1. Add methods to the `Manager` struct in `internal/core/core.go`
+2. Write comprehensive unit tests in `internal/core/core_test.go`
+3. Ensure tests achieve good coverage
+4. Update documentation
+
+### Modifying Storage
+
+1. Update `pkg/storage/storage.go`
+2. Add/update tests in `pkg/storage/storage_test.go`
+3. Consider backward compatibility with existing data files
+4. Test migration paths if changing data format
+
+## Performance Considerations
+
+- Commands should execute in <100ms for typical use cases
+- Use in-memory maps for fast lookups (O(1) complexity)
+- Minimize file I/O operations
+- Profile code if adding complex features:
+  ```bash
+  go test -cpuprofile=cpu.prof -bench=.
+  go tool pprof cpu.prof
+  ```
+
+## Documentation
+
+When adding features, update:
+
+- `README.md` - For user-facing features
+- `EXAMPLES.md` - Add practical examples
+- Code comments - For exported functions
+- `ROADMAP.md` - Mark completed items, add new goals
+
+## Release Process
+
+1. Update version in relevant files
+2. Update CHANGELOG (if exists)
+3. Create a git tag:
+   ```bash
+   git tag -a v1.0.0 -m "Release version 1.0.0"
+   git push origin v1.0.0
+   ```
+
+4. Build release binaries:
+   ```bash
+   make build-all
+   ```
+
+5. Create GitHub release with binaries
+
+## Getting Help
+
+- Check existing issues and pull requests
+- Read the ROADMAP.md for project direction
+- Ask questions in issue comments
+- Reach out to maintainers
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Provide constructive feedback
+- Focus on what is best for the project
+- Show empathy towards other contributors
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same license as the project (MIT License).
+
+---
+
+Thank you for contributing to Zut! 🚀