Add getting started and contributing guide

CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to the Bootc Operator
+
+Welcome! The Bootc Operator is a Kubernetes operator for managing
+[bootc](https://github.com/bootc-dev/bootc) nodes. We welcome contributions of
+all kinds: bug reports, feature requests, documentation improvements, and code
+changes.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Development Environment](#development-environment)
+- [Building](#building)
+- [Testing](#testing)
+- [Code Style](#code-style)
+- [Submitting Changes](#submitting-changes)
+- [Community](#community)
+
+## Prerequisites
+
+Before contributing, make sure you have the following installed:
+
+- **Go** (see `go.mod` for the required version)
+- **Make**
+- **Podman**
+- **kubectl**
+
+For end-to-end testing you will also need:
+
+- [bink](https://github.com/bootc-dev/bink) — lightweight Kubernetes clusters
+  for testing
+- [skopeo](https://github.com/containers/skopeo) — container image inspection
+
+Tool dependencies like `controller-gen`, `kustomize`, `golangci-lint`, and
+`setup-envtest` are downloaded automatically to `./bin/` by the Makefile when
+needed.
+
+## Development Environment
+
+Most contributors work on a Linux host with Go and Podman available.
+
+Before diving into the code, familiarize yourself with the project from a user
+perspective by reading the [README](README.md) and the
+[Architecture](docs/ARCHITECTURE.md) document. We also recommend getting
+familiar with [bink](https://github.com/bootc-dev/bink), which is used to
+create lightweight Kubernetes clusters backed by bootc nodes for development
+and testing.
+
+## Testing
+
+Build and test instructions are in the
+[Getting Started](docs/GETTING_STARTED.md) guide. Please make sure your changes
+pass both unit and end-to-end tests locally before submitting a pull request.
+
+## Code Style
+
+### Go
+
+- Run `make fmt` and `make vet` before submitting.
+- Run `make lint` to check with
+  [golangci-lint](https://golangci-lint.run/). Use `make lint-fix` to apply
+  automatic fixes.
+- All Go files must include the SPDX license header:
+
+  ```go
+  // SPDX-License-Identifier: Apache-2.0
+  ```
+## Submitting Changes
+
+### Before Writing a Big Patch
+
+If you are planning a large change, please **open an issue first** to discuss
+the approach. This avoids wasted effort and helps maintainers give early
+feedback.
+
+### Developer Certificate of Origin
+
+This project uses the [Developer Certificate of Origin](https://developercertificate.org/)
+(DCO). You must sign off each commit to certify that you have the right to
+submit it under the project's open source license.
+
+Add a sign-off line to your commits:
+
+```
+Signed-off-by: Your Name <your.email@example.com>
+```
+
+Use `git commit -s` to add this automatically. Your sign-off name must match
+your real name.
+
+### Commit Style
+
+Follow a commit style similar to the Linux kernel:
+
+1. **Subject line**: a short contextual prefix, imperative mood, under 72
+   characters, no trailing period.
+2. **Body**: separated by a blank line, wrapped at 72 characters. Explain
+   *what* changed and *why*.
+3. Use `Closes: #<number>` or `Fixes: #<number>` to link to issues.
+
+### Pull Request Process
+
+1. Fork the repository and create a topic branch from `main`.
+2. Make your changes in small, focused commits.
+3. Ensure all checks pass locally:
+
+   ```shell
+   make fmt manifests generate
+   make vet
+   make lint
+   make unit
+   ```
+
+4. Push your branch and open a pull request against `main`.
+5. Describe the change clearly in the PR description — what it does and why.
+6. Address review feedback. Maintainers may request changes before merging.
+
+### Code Review
+
+All submissions require review before merging. Reviewers look for:
+
+- Correctness and test coverage
+- Consistency with existing patterns
+- Clear commit messages
+- Generated files kept in sync
+
+## Community
+
+- **Issues**: Use [GitHub Issues](https://github.com/bootc-dev/bootc-operator/issues)
+  to report bugs or request features.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+[Apache License 2.0](LICENSE).

docs/GETTING_STARTED.md

@@ -0,0 +1,160 @@
+# Getting Started
+
+This guide covers how to build, test, and develop the Bootc Operator.
+
+## Prerequisites
+
+- **Go** (see `go.mod` for the required version)
+- **Make**
+- **Podman**
+- **kubectl**
+
+For end-to-end testing you will also need:
+
+- [bink](https://github.com/bootc-dev/bink) — lightweight Kubernetes clusters
+  backed by bootc nodes
+- [skopeo](https://github.com/containers/skopeo) — container image inspection
+
+Tool dependencies like `controller-gen`, `kustomize`, `golangci-lint`, and
+`setup-envtest` are downloaded automatically to `./bin/` by the Makefile.
+
+## Building
+
+```shell
+make build           # Build all binaries (manager + daemon) to ./bin/
+make buildimg        # Build the container image (default: bootc-operator:dev)
+```
+
+The `bootc-operator` container image contains both the controller and daemon
+binaries.
+
+After modifying API types in `api/`, regenerate CRDs and code:
+
+```shell
+make manifests       # Regenerate CRD and RBAC manifests
+make generate        # Regenerate DeepCopy implementations
+```
+
+## Running Unit Tests
+
+Unit tests use the controller-runtime
+[envtest](https://book.kubebuilder.io/reference/envtest) framework, which
+provides a local control plane (etcd + API server) without a full cluster. The
+required binaries are downloaded automatically.
+
+```shell
+make unit            # Run all unit tests
+make unit V=1        # Verbose output
+make unit RUN=Foo    # Run tests matching "Foo"
+```
+
+## Running End-to-End Tests
+
+E2E tests run against a real [bink](https://github.com/bootc-dev/bink) cluster.
+The full workflow is:
+
+```shell
+make buildimg        # Build the operator container image
+make deploy-bink     # Start a bink cluster and deploy the operator
+make e2e             # Run the e2e test suite
+```
+
+> [!NOTE]
+> The container image must be rebuilt and pushed to the bink registry after
+> every code change. Run `make buildimg` followed by `make deploy-bink` to
+> pick up your latest changes in the cluster.
+
+The bink cluster includes an internal container registry. From the host, push
+images to `localhost:5000`:
+
+```shell
+podman push --tls-verify=false localhost:5000/my-image:latest
+```
+
+From inside the cluster, the same image is available at
+`registry.cluster.local:5000`:
+
+```yaml
+image: registry.cluster.local:5000/my-image:latest
+```
+
+Each e2e test creates a dedicated worker node for the duration of the test and
+tears it down when the test completes. The freshly provisioned node ensures
+that each test starts from a clean state.
+
+Options:
+
+```shell
+make e2e V=1         # Verbose streaming output
+make e2e RUN=Foo     # Run tests matching "Foo"
+```
+
+### Finding Test Logs
+
+Each e2e test automatically gathers diagnostic logs when it completes
+(regardless of pass or fail). Logs are written to `_output/logs/<test-name>/`
+and include:
+
+- Operator pod logs
+- Pod and deployment descriptions
+- BootcNodePool and BootcNode descriptions
+- Kubernetes events
+- Node descriptions and journal logs for each worker node
+
+You can also manually gather logs from a running cluster:
+
+```shell
+make gather-bink
+```
+
+This collects the same diagnostics into `_output/logs/gather-bink/`.
+
+To tear down the cluster when done:
+
+```shell
+make teardown-bink
+```
+
+By default, `deploy-bink` and `e2e` share the same cluster named `e2e`. To use
+a separate development cluster:
+
+```shell
+make deploy-bink BINK_CLUSTER_NAME=dev
+```
+
+## Investigating CI Failures
+
+CI runs on [GitHub Actions](https://github.com/bootc-dev/bootc-operator/actions)
+and consists of three jobs: `unit`, `build-bink`, and `e2e`. When a run fails,
+you can inspect it using the `gh` CLI.
+
+View a run summary:
+
+```shell
+gh run view <run-id> --repo bootc-dev/bootc-operator
+```
+
+### Downloading E2E Logs
+
+The e2e job uploads diagnostic logs as a GitHub Actions artifact named
+`e2e-logs`. These contain the same logs collected by `make gather-bink`
+(operator pod logs, node journals, event dumps, etc.). Download them with:
+
+```shell
+gh run download <run-id> --repo bootc-dev/bootc-operator
+```
+
+This creates a local `e2e-logs/` directory with per-test subdirectories
+matching the structure described in [Finding Test Logs](#finding-test-logs).
+
+## Code Style
+
+Before submitting changes, make sure the code passes formatting, vetting, and
+linting:
+
+```shell
+make fmt             # Run go fmt
+make vet             # Run go vet
+make lint            # Run golangci-lint
+make lint-fix        # Run golangci-lint with automatic fixes
+```