docs: rewrite CONTRIBUTING.md following chezroot style

- Add comprehensive TLDR section with key requirements
- Expand development environment setup with detailed prerequisites
- Add coverage enforcement documentation (100% for business logic)
- Include testing patterns and best practices
- Document automation pipeline and CI workflows
- Improve structure with clear sections and table of contents
- Model after main-branch/chezroot contributing guide

Author: jcouball

CONTRIBUTING.md

@@ -1,156 +1,282 @@
 # Contributing to MkDocs Snippet Lens
 
-Thank you for your interest in contributing to MkDocs Snippet Lens! We welcome
-contributions from the community.
+First, thank you for considering contributing to MkDocs Snippet Lens. This project is
+a community effort, and every contribution is valued.
 
-## Development Workflow
+This guide outlines the standards and procedures for contributing, from setting up your
+environment to submitting your changes. Please read it carefully to ensure your
+contributions can be merged smoothly.
 
-All changes to this project must follow this workflow:
+- [TLDR](#tldr)
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Environment Setup](#development-environment-setup)
+- [Development Workflow](#development-workflow)
+- [Testing & Coverage](#testing--coverage)
+- [Submitting Changes](#submitting-changes)
+- [Automation Pipeline](#automation-pipeline)
 
-### 1. Work on a Feature Branch
+## TLDR
 
-**Never commit directly to `main`.** All changes must be made on a feature branch:
+Here are the most important guidelines:
 
-```bash
-git checkout main
-git pull origin main
-git checkout -b feature/your-feature-name
-```
+- **Prerequisites**: You must have Node.js (>= 20) and npm installed.
+- **One-Time Setup**: Run `npm ci` after cloning to install all development dependencies
+  and Git hooks.
+- **Conventional Commits**: All commit messages must follow the Conventional Commits
+  standard (e.g., `feat: ...`, `fix: ...`). A local Git hook will enforce this.
+- **Tests are Required**: All new features or bug fixes must include corresponding
+  tests.
+- **Update Documentation**: Any change that impacts users (new features, settings, etc.)
+  must be documented appropriately.
+- **Ensure CI passes locally**: Before submitting a pull request, run `npm run test:all`
+  and ensure all checks (linting, testing, building) pass.
+- **Rebase Workflow**: Always work on a new branch. Your pull request must be rebased on
+  the latest `main` branch before it will be merged with a fast-forward merge.
 
-### 2. Make Your Changes
+## Code of Conduct
 
-- Write clear, concise commit messages following
-  [Conventional Commits](https://www.conventionalcommits.org/)
-- Ensure all tests pass: `npm run test:all`
-- Maintain 100% test coverage for business logic
-- Follow the existing code style (enforced by ESLint)
+This project and everyone participating in it is governed by our community standards.
+By participating, you are expected to uphold respectful and professional behavior.
 
-### 3. Keep Your Branch Up to Date
+## Getting Started
 
-Before creating a pull request, rebase your branch on the latest `main`:
+Before you begin, you'll need to fork and clone the repository.
 
-```bash
-git checkout main
-git pull origin main
-git checkout your-feature-branch
-git rebase main
-```
+1. Fork the repository on GitHub.
 
-Resolve any conflicts that arise during the rebase.
+2. Clone your fork to your local machine:
 
-### 4. Submit a Pull Request
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/mkdocs-snippet-lens.git
+   cd mkdocs-snippet-lens
+   ```
 
-1. Push your feature branch to GitHub:
+3. Add the upstream remote to keep your fork in sync:
 
    ```bash
-   git push origin feature/your-feature-name
+   git remote add upstream https://github.com/main-branch/mkdocs-snippet-lens.git
    ```
 
-2. Create a pull request on GitHub from your feature branch to `main`
+## Development Environment Setup
 
-3. Ensure all CI checks pass (linting, type checking, tests on all platforms)
+This project uses Node.js and TypeScript for the VS Code extension, with npm for
+dependency management and tooling.
 
-4. Request a review from a maintainer
+### Prerequisites
 
-### 5. Pull Request Requirements
+You must have the following tools installed on your local machine:
 
-Your pull request **must**:
+- **Node.js**: Version 20.0.0 or newer.
+- **npm**: This is included with Node.js.
+- **Visual Studio Code**: For testing the extension.
 
-- Pass all CI checks (linting, type checking, unit tests, integration tests)
-- Be reviewed and approved by at least one maintainer
-- Be rebased on the latest `main` branch (no merge commits)
-- Have a clean, linear commit history
+### Install Dependencies and Tooling
 
-### 6. Merging
+Once you have the prerequisites, you can install all project dependencies and
+development tools by running:
 
-Once approved, a maintainer will merge your PR using a **fast-forward merge**. This
-means:
+```bash
+npm ci
+```
 
-- Your branch must be rebased on the latest `main`
-- No merge commits will be created
-- The commit history remains linear
+This command will:
 
-If `main` has been updated since your last rebase, you'll need to rebase again before
-the PR can be merged.
+1. Install all Node.js dependencies from the `package-lock.json` file.
+2. Run the `prepare` script in `package.json`, which uses Husky to set up the
+   `commit-msg` Git hook (`.husky/commit-msg`).
 
-## Development Setup
+The development tools (`eslint`, `typescript`, `mocha`, `c8`) are managed via
+`package.json` and invoked with npm scripts. You do not need to install them globally.
 
-### Prerequisites
+If you later pull changes that modify `package-lock.json`, re-run `npm ci` to keep
+local development tooling in sync.
 
-- Node.js 20.x or later
-- npm 10.x or later
-- Visual Studio Code
+### Editor Setup (VS Code)
 
-### Setup Steps
+For the best development experience, we recommend using VS Code with the following
+extensions:
 
-1. Clone the repository:
+- **ESLint**: `dbaeumer.vscode-eslint`
+- **TypeScript and JavaScript Language Features**: Built-in
 
-   ```bash
-   git clone https://github.com/main-branch/mkdocs-snippet-lens.git
-   cd mkdocs-snippet-lens
-   ```
+This repository includes a `.vscode/settings.json` file that will automatically
+configure these extensions to use the project's rules.
 
-2. Install dependencies:
+## Development Workflow
 
-   ```bash
-   npm ci
-   ```
+The `package.json` scripts are the single source of truth for all common development
+tasks.
 
-3. Build the extension:
+### Main Command
 
-   ```bash
-   npm run compile
-   ```
+Before submitting a pull request, you must run the full test suite locally:
 
-4. Run tests:
+```bash
+npm run test:all
+```
 
-   ```bash
-   npm run test:all
-   ```
+This command runs unit tests and integration tests on your local machine. This is
+similar to what our GitHub workflow uses.
 
-### Available Scripts
+### Other Useful Commands
 
-- `npm run lint` - Run ESLint
+- `npm run lint` - Run ESLint to check code style
 - `npm run check-types` - Run TypeScript type checking
 - `npm run test:unit` - Run unit tests with coverage
-- `npm run test:integration` - Run integration tests
-- `npm run test:all` - Run all tests
+- `npm run test:integration` - Run integration tests in VS Code
 - `npm run compile` - Build the extension
 - `npm run watch` - Watch mode for development
 
-## Testing
+## Testing & Coverage
 
-### Unit Tests
+This project enforces 100% statement coverage on business logic modules to maintain
+code quality and ensure all code paths are tested.
 
-Unit tests are located in `src/test/unit/` and test individual modules in isolation.
-All business logic must have 100% test coverage.
+### Coverage Requirement
 
-### Integration Tests
+All contributions must maintain 100% statement coverage for business logic modules. The
+CI pipeline will automatically fail if coverage drops below this threshold.
 
-Integration tests are in `src/test/integration/` and test the extension running in
-VS Code.
+Note: VS Code integration modules (`extension.ts`, `snippetLinkProvider.ts`,
+`snippetHoverProvider.ts`, `previewManager.ts`, `diagnosticManager.ts`) are excluded
+from coverage requirements as they are tested via integration tests.
 
 ### Running Tests Locally
 
 ```bash
-# Unit tests only
+# Run unit tests with coverage
 npm run test:unit
 
-# Integration tests only
+# Run integration tests
 npm run test:integration
 
-# All tests
+# Run all tests
 npm run test:all
 ```
 
-## Code Style
+### Understanding Coverage
+
+The coverage tooling measures statement coverage:
+
+- **Statement coverage** = whether each executable statement was run by tests
+
+The coverage report shows:
+
+- Green = covered by tests
+- Red = NOT covered (needs tests added)
+- Gray = not executable (comments, declarations)
+
+### Adding Tests for New Code
+
+When adding new features or fixing bugs:
+
+1. Write tests that cover all new code paths
+2. Run `npm run test:unit` to verify 100% coverage on business logic
+3. If coverage is below 100%, review the coverage report to identify uncovered lines
+4. Add tests for the uncovered statements
+
+### Common Patterns for Testability
+
+The codebase follows these patterns to enable testing:
+
+- **Separate business logic from VS Code integration**: Business logic modules are in
+  pure TypeScript functions that can be tested in isolation.
+- **Integration tests for VS Code features**: Features that require VS Code APIs are
+  tested via integration tests that run in a real VS Code environment.
+
+Example:
+
+```typescript
+// Business logic (100% coverage required)
+export function createDiagnosticInfos(
+  locations: SnippetLocation[],
+  resolver: (path: string) => string | null
+): DiagnosticInfo[] {
+  // Pure function - easily testable
+}
+
+// VS Code integration (integration tests)
+export class DiagnosticManager {
+  updateDiagnostics(document: vscode.TextDocument): void {
+    // Uses VS Code APIs - tested via integration
+  }
+}
+```
+
+### Viewing Coverage Reports
+
+After running `npm run test:unit`, you can view the coverage report:
+
+1. Open `coverage/lcov-report/index.html` in your browser
+2. Click on individual files to see line-by-line coverage
+
+## Submitting Changes
+
+### Commit Message Format
+
+This project uses Conventional Commits. This format is strictly enforced by a Git hook
+and our CI pipeline.
+
+For the full specification and examples, see the
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) website.
+
+After running `npm ci`, a `commit-msg` hook is installed that automatically lints your
+commit message with `commitlint`.
+
+- Your commit message must follow the format: `<type>(<scope>): <subject>`.
+- Allowed types are: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
+  `build`, `ci`, `chore`, `revert`.
+- For details on all rules, see `.commitlintrc.yml`.
+
+Examples:
+
+- `feat(diagnostics): add error highlighting for missing files`
+- `fix: correct path resolution on Windows`
+- `docs: update installation instructions in README`
+
+### Pull Request Process
+
+1. Create a feature branch from the `main` branch.
+
+2. Make your changes.
+
+   **Important Contributor Requirements**
+
+   - **All new code requires tests**: Any new feature or bug fix must be accompanied by
+     corresponding tests.
+   - **Documentation must be updated**: Any change that impacts user behavior (new
+     commands, settings, etc.) must be documented in the `README.md`.
+
+3. Ensure your code passes all local checks by running `npm run test:all`.
+
+4. Rebase your branch on the latest `main`:
+
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+   If you encounter conflicts during the rebase, resolve them and continue:
+
+   ```bash
+   git add <files>
+   git rebase --continue
+   ```
+
+5. Push your branch and open a pull request against `main-branch/mkdocs-snippet-lens:main`.
+
+6. Ensure all CI checks on the pull request pass.
+
+## Automation Pipeline
 
-- Follow the existing code patterns
-- Use TypeScript strict mode
-- Document public APIs with JSDoc comments
-- Keep functions small and focused
-- Separate VS Code integration from business logic
+We use a set of GitHub Actions to automate linting, testing, and quality checks.
 
-## Questions?
+- **Continuous Integration**: On every pull request,
+  `.github/workflows/continuous-integration.yml` runs linting, type checking, unit
+  tests, integration tests (on Ubuntu, macOS, and Windows), and builds the extension.
+- **Conventional Commits**: Commit messages are validated during CI to ensure they
+  follow the Conventional Commits standard.
+- **100% Coverage**: The CI pipeline enforces 100% statement coverage on business logic
+  modules.
 
-If you have questions about contributing, please open an issue for discussion.