CONTRIBUTING.md

   1 # Contributing
   2
   3 This repository contains the Chef code used to configure OpenStreetMap's infrastructure.
   4 This guide walks you through running the same checks as CI locally before opening a pull request.
   5
   6 ## What you should run before a pull request
   7
   8 At a minimum, please run:
   9
  10 - **Cookstyle** (lint/style): `bundle exec cookstyle`
  11 - **Test Kitchen** for the cookbooks/roles you changed or added (integration): `bundle exec kitchen test <suite>-<platform>`
  12
  13 CI runs a large matrix; contributors are not expected to run every Kitchen instance locally.
  14
  15 ## Quick start (if you already have Ruby + Docker)
  16
  17 From the repository root:
  18
  19 ```bash
  20 bundle install
  21 bundle exec cookstyle
  22 bundle exec kitchen list
  23 bundle exec kitchen test dns-ubuntu-2204
  24 ```
  25
  26 Replace `dns-ubuntu-2204` with a Kitchen instance relevant to the cookbooks/roles you changed.
  27
  28 ## Workflow
  29
  30 We use the "fork and pull request" workflow:
  31
  32 - Fork the repository
  33 - Create a topic branch
  34 - Open a pull request back to `openstreetmap/chef`
  35
  36 GitHub has an overview at https://help.github.com/articles/using-pull-requests
  37
  38 ## Local test setup
  39
  40 ### Prerequisites
  41
  42 - **Docker**
  43         - macOS: Docker Desktop
  44         - Linux: Docker Engine
  45         - Windows: WSL2 + Docker may work, but is not used by the operations team and may not work in your environment (see below).
  46 - **Ruby** (see [.ruby-version](.ruby-version)) and **Bundler**
  47 - `git`
  48
  49 We recommend using `rbenv` to manage Ruby versions. On macOS, Homebrew is often the easiest way to install it.
  50
  51 ### Recommended setup (rbenv + Bundler)
  52
  53 The steps below work on macOS and Linux. The macOS-only steps are called out explicitly.
  54
  55 1) Install Docker
  56
  57 - macOS: Docker Desktop - https://www.docker.com/products/docker-desktop
  58 - Linux: Docker Engine - https://docs.docker.com/engine/install/
  59
  60 2) macOS only: install Homebrew (if you do not already have it)
  61
  62 - https://brew.sh/
  63
  64 3) Install `rbenv`
  65
  66 - https://github.com/rbenv/rbenv#installation
  67
  68 `rbenv` is a Ruby version manager. It lets you use the Ruby version this repository expects without changing your system Ruby.
  69
  70 If you do not use `rbenv`, omit the `rbenv exec` prefix in the commands below.
  71
  72 4) macOS only: increase the open file limit (often needed)
  73
  74 If you see errors like `Too many open files (Errno::EMFILE)` while running tests:
  75
  76 ```bash
  77 ulimit -n 1024
  78 ```
  79
  80 To make it permanent, add the line above to your shell profile (for example `~/.zshrc`).
  81
  82 5) Install the Ruby version for this repo
  83
  84 From the repository root:
  85
  86 ```bash
  87 rbenv install --skip-existing
  88 ```
  89
  90 6) Install Ruby gems
  91
  92 ```bash
  93 rbenv exec gem install bundler
  94 rbenv exec bundle install
  95 ```
  96
  97 ## Running the checks
  98
  99 ### 1) Cookstyle (lint and style)
 100
 101 Cookstyle checks Chef/Ruby style and common issues.
 102
 103 ```bash
 104 rbenv exec bundle exec cookstyle
 105 ```
 106
 107 If you prefer not to install Ruby locally, you can run Cookstyle via Docker:
 108
 109 ```bash
 110 docker compose run --rm cookstyle
 111 ```
 112
 113 If you only want to lint the files you are committing, there is a sample pre-commit hook at [hooks/pre-commit](hooks/pre-commit).
 114 Copy it to `.git/hooks/pre-commit` and make it executable.
 115
 116 ### 2) Test Kitchen (integration tests)
 117
 118 We use Test Kitchen with InSpec and the Dokken driver to converge recipes and verify behaviour inside containers.
 119
 120 1) List available instances:
 121
 122 ```bash
 123 rbenv exec bundle exec kitchen list
 124 ```
 125
 126 Kitchen instances are named `<suite>-<platform>`.
 127 The suite is usually the cookbook/role under test (see [.kitchen.yml](.kitchen.yml)), and the platform is the OS image.
 128
 129 The available Kitchen suites and platforms are defined in [.kitchen.yml](.kitchen.yml).
 130 The InSpec integration tests themselves live under [test/integration/](test/integration/).
 131 If your change adds a new cookbook, please add a corresponding suite to [.kitchen.yml](.kitchen.yml) and include appropriate integration tests.
 132
 133 2) Run a specific instance:
 134
 135 ```bash
 136 rbenv exec bundle exec kitchen test dns-ubuntu-2204
 137 ```
 138
 139 `kitchen test` will create the container, converge, verify, then destroy it.
 140
 141 For faster iteration, you can split the steps:
 142
 143 ```bash
 144 rbenv exec bundle exec kitchen converge dns-ubuntu-2204
 145 rbenv exec bundle exec kitchen verify dns-ubuntu-2204
 146 rbenv exec bundle exec kitchen destroy dns-ubuntu-2204
 147 ```
 148
 149 #### Debugging a failed converge
 150
 151 If `kitchen converge` fails, it can be useful to inspect the running test container.
 152
 153 1) Find the container name by running `docker ps` (example output):
 154
 155 ```text
 156 CONTAINER ID   IMAGE                               COMMAND          CREATED          STATUS          PORTS     NAMES
 157 3b83c7f96575   9a7e6edc5b-dns-ubuntu-2204:latest   "/bin/systemd"   14 minutes ago   Up 14 minutes             9a7e6edc5b-dns-ubuntu-2204
 158 ```
 159
 160 2) Enter the container:
 161
 162 ```bash
 163 docker exec -it 9a7e6edc5b-dns-ubuntu-2204 bash -l
 164 ```
 165
 166 Once you are finished debugging, remember to clean up the instance:
 167
 168 ```bash
 169 rbenv exec bundle exec kitchen destroy dns-ubuntu-2204
 170 ```
 171
 172 ## Windows (WSL2)
 173
 174 It may be possible to run the toolchain under WSL2 (for example Ubuntu on WSL2) with Docker.
 175 However, the operations team do not use WSL2, and we cannot guarantee it will work or be able to troubleshoot WSL2-specific issues.
 176
 177 If you try this route, aim to match the Linux instructions as closely as possible and ensure Docker is reachable from within WSL2.
 178
 179 ## Troubleshooting
 180
 181 - **Docker is not running**: start Docker Desktop (macOS) or the Docker service (Linux).
 182 - **Open file limit errors on macOS**: increase `ulimit -n` as described above.
 183 - **Kitchen networking issues**: if Docker has IPv6 disabled, Dokken may fail to create its network; enabling IPv6 in Docker's settings can help.
 184
 185 ## Pull request checklist
 186
 187 - Run `bundle exec cookstyle` locally
 188 - Run relevant `kitchen test <suite>-<platform>` instances for the cookbooks/roles you changed or added
 189 - Keep changes focused and include context in the pull request description
 190
 191 ## Need help?
 192
 193 If you get stuck, the operations team are available in `#osmf-operations` on `irc.oftc.net`.
 194 You can access `#osmf-operations` via https://irc.openstreetmap.org/ or via the Matrix IRC bridge in [#\_oftc_#osmf-operations](https://matrix.to/#/#_oftc_#osmf-operations:matrix.org).