Add contributing docs and expand flake dev environment

Author: netbrain

.config/.cspell.json

@@ -2,8 +2,12 @@
     "version": "0.2",
     "language": "en",
     "words": [
+        "devcontainer",
+        "direnv",
+        "hadolint",
         "Kickr",
         "netbrain",
+        "shellcheck",
         "WQHD",
         "zwift",
         "zwifters"

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+Thanks for your interest in contributing to netbrain/zwift!
+
+## Quick Start
+
+### Using Nix (recommended)
+
+```bash
+nix develop
+# Or with direnv: direnv allow
+```
+
+### Using VS Code Devcontainer
+
+Open the project in VS Code and select "Reopen in Container" when prompted.
+
+## Documentation
+
+For detailed setup instructions, available tools, and guidelines, see the
+[Contributing Guide](https://netbrain.github.io/zwift/contributing/).
+
+## Issues and PRs
+
+- Check [open issues](https://github.com/netbrain/zwift/issues) for something
+  to work on
+- Feel free to open a PR - all contributions are welcome

docs/contributing/development.md

@@ -0,0 +1,140 @@
+---
+title: Development Environment
+parent: Contributing
+nav_order: 1
+---
+
+This project provides two options for setting up a development environment with
+all the linting and development tools used in CI.
+
+## Option 1: Nix Flakes (Recommended)
+
+[Nix flakes](https://nixos.wiki/wiki/Flakes) provide a reproducible development
+environment that works on any Linux distribution.
+
+### Prerequisites
+
+- [Nix](https://nixos.org/download.html) with flakes enabled
+- Optionally [direnv](https://direnv.net/) for automatic shell activation
+
+#### Enabling Flakes
+
+If you haven't enabled flakes, add this to `~/.config/nix/nix.conf`:
+
+```ini
+experimental-features = nix-command flakes
+```
+
+### Entering the Development Shell
+
+```bash
+# One-time use
+nix develop
+
+# Or with direnv (recommended)
+direnv allow
+```
+
+### Available Tools
+
+The development shell includes all tools used in CI:
+
+| Tool | Purpose |
+|------|---------|
+| `shellcheck` | Bash script linting |
+| `shfmt` | Bash script formatting |
+| `nil` | Nix language diagnostics |
+| `nixfmt-rfc-style` | Nix code formatting |
+| `hadolint` | Dockerfile linting |
+| `markdownlint-cli2` | Markdown linting |
+| `cspell` | Spell checking |
+| `actionlint` | GitHub Actions workflow linting |
+| `yamllint` | YAML linting |
+| `podman` | Container runtime |
+| `gh` | GitHub CLI |
+
+## Option 2: VS Code Devcontainer
+
+If you use VS Code and prefer containers over Nix, a
+[devcontainer](https://containers.dev/) configuration is included.
+
+### Requirements
+
+- [VS Code](https://code.visualstudio.com/)
+- [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+- Docker or Podman
+
+### Getting Started
+
+1. Open the project in VS Code
+2. When prompted, click "Reopen in Container"
+3. Or use the command palette: `Dev Containers: Reopen in Container`
+
+The devcontainer includes:
+
+- Docker-in-docker for building images
+- Nix with `nil` language server
+- shellcheck and hadolint
+- VS Code extensions for real-time linting feedback
+
+## Running Linters Locally
+
+Run these before submitting a PR to catch issues early:
+
+```bash
+# Bash scripts
+shellcheck *.sh bin/*.sh
+shfmt -d *.sh bin/*.sh
+
+# Nix files
+nil diagnostics *.nix
+nixfmt-rfc-style --check *.nix
+
+# Dockerfile
+hadolint Dockerfile
+
+# Markdown
+markdownlint-cli2 "**/*.md"
+cspell "**/*.md"
+
+# GitHub Actions
+actionlint
+
+# YAML
+yamllint .github/workflows/
+```
+
+## Building the Documentation Locally
+
+The documentation uses Jekyll with the just-the-docs theme.
+
+```bash
+cd docs
+bundle install
+bundle exec jekyll serve
+```
+
+Then open <http://localhost:4000> in your browser.
+
+## Building the Container Image
+
+```bash
+# Build the image
+podman build -t zwift:dev .
+
+# Or use the build script
+./bin/build-image.sh
+```
+
+## Testing Changes
+
+```bash
+# Dry run to see what would be executed
+DRYRUN=1 ./zwift.sh
+
+# Run in foreground for debugging
+ZWIFT_FG=1 ./zwift.sh
+
+# Interactive mode (drops into container shell)
+INTERACTIVE=1 ./zwift.sh
+```

docs/contributing/index.md

@@ -0,0 +1,28 @@
+---
+title: Contributing
+nav_order: 6
+has_children: true
+description: "How to contribute to the project"
+---
+
+Thanks for your interest in contributing! This project welcomes all
+contributions, whether it's bug fixes, new features, documentation
+improvements, or issue reports.
+
+## Ways to Contribute
+
+- **Report bugs** - Open an [issue](https://github.com/netbrain/zwift/issues)
+  with details about the problem
+- **Suggest features** - Start a
+  [discussion](https://github.com/netbrain/zwift/discussions) to propose new
+  ideas
+- **Submit PRs** - Fix bugs or implement features
+- **Improve docs** - Help make the documentation clearer
+
+## Getting Started
+
+1. Fork the repository
+2. Set up the [development environment](development.html)
+3. Make your changes
+4. Run the linters locally to catch issues early
+5. Submit a pull request

flake.nix

@@ -256,10 +256,38 @@
 
       devShells.x86_64-linux.default = pkgs.mkShell {
         packages = with pkgs; [
+          # Bash
           shellcheck
           shfmt
+
+          # Nix
+          nil
+          nixfmt-rfc-style
+
+          # Docker
+          hadolint
+
+          # Markdown
+          nodePackages.markdownlint-cli2
+          nodePackages.cspell
+
+          # Documentation (Jekyll)
           ruby
           bundler
+
+          # Container runtime
+          podman
+
+          # GitHub
+          gh
+          actionlint
+
+          # YAML
+          yamllint
+
+          # Utilities
+          curl
+          jq
         ];
       };