Merge pull request #84 from ory/docs/update_docs

docs: contributing and readme update

Author: KT-Doan

.githooks/pre-commit

@@ -11,7 +11,7 @@ if [ -n "$(gofmt -l .)" ]; then
     echo "Error: The following files are not formatted:"
     gofmt -l .
     echo ""
-    echo "Run 'make fmt' to fix formatting."
+    echo "Run 'make format' to fix formatting."
     exit 1
 fi
 
@@ -21,12 +21,17 @@ go vet ./...
 
 # Lint
 echo "Running golangci-lint..."
-if command -v golangci-lint &> /dev/null; then
+if [ -x ".bin/golangci-lint" ]; then
+    .bin/golangci-lint run
+elif command -v golangci-lint &> /dev/null; then
     golangci-lint run
-elif [ -x "$(go env GOPATH)/bin/golangci-lint" ]; then
-    "$(go env GOPATH)/bin/golangci-lint" run
 else
-    echo "Warning: golangci-lint not found, skipping. Install with: make tools"
+    GOPATH_BIN="$(go env GOPATH 2>/dev/null)/bin/golangci-lint"
+    if [ -n "$GOPATH_BIN" ] && [ -x "$GOPATH_BIN" ]; then
+        "$GOPATH_BIN" run
+    else
+        echo "Warning: golangci-lint not found, skipping. Install with: make deps"
+    fi
 fi
 
 # Build check

CONTRIBUTING.md

@@ -6,9 +6,9 @@ Thank you for your interest in contributing to the Ory Terraform Provider!
 
 ### Prerequisites
 
-- [Go](https://golang.org/doc/install) >= 1.21
+- [Go](https://golang.org/doc/install) (see version in `go.mod`)
 - [Terraform](https://www.terraform.io/downloads) >= 1.0
-- An [Ory Network](https://console.ory.sh/) account for testing
+- An [Ory Network](https://console.ory.sh/) account for acceptance testing
 
 ### Building
 
@@ -17,14 +17,16 @@ Thank you for your interest in contributing to the Ory Terraform Provider!
 git clone https://github.com/ory/terraform-provider-ory.git
 cd terraform-provider-ory
 
-# Install development tools and set up git hooks
-make tools
-make hooks
+# Install dependencies
+make deps
+
+# Set up pre-commit hooks
+git config core.hooksPath .githooks
 
 # Build
 make build
 
-# Install locally
+# Install locally (to ~/.terraform.d/plugins/)
 make install
 ```
 
@@ -42,8 +44,8 @@ The provider has two types of tests:
 Unit tests can be run without any credentials:
 
 ```bash
-make test           # Run all unit tests
-make test-short     # Run unit tests in short mode
+make test           # Run all unit tests with coverage
+make test-short     # Run unit tests in short mode (CI runs these with coverage enabled)
 ```
 
 ### Acceptance Tests
@@ -58,20 +60,26 @@ Acceptance tests run against a **pre-created Ory project**. The project must be
 cp .env.example .env
 ```
 
-The `.env` file is gitignored and automatically loaded by `make` targets. At minimum you need:
+The `.env` file is gitignored and automatically loaded by `make` targets.
+
+**Required** (validated by `make env-check`):
 
 ```bash
-# Workspace credentials
 ORY_WORKSPACE_API_KEY=ory_wak_...
 ORY_WORKSPACE_ID=...
+```
+
+**Recommended** (needed by most resource tests):
 
-# Pre-created test project
+```bash
 ORY_PROJECT_ID=...
 ORY_PROJECT_SLUG=...
 ORY_PROJECT_API_KEY=ory_pat_...
 ORY_PROJECT_ENVIRONMENT=prod
 ```
 
+When set, tests use this persistent project instead of creating ephemeral ones. The project must have keto namespaces and dynamic client registration configured. See `.env.example` for the full list of variables.
+
 #### Running Acceptance Tests
 
 ```bash
@@ -94,6 +102,8 @@ Some tests require specific Ory plan features. Enable them with environment vari
 | `ORY_PROJECT_TESTS_ENABLED=true` | Run project creation/deletion tests |
 | `ORY_EVENT_STREAM_TESTS_ENABLED=true` | Run event stream tests (requires Enterprise plan + AWS setup below) |
 
+> **Note:** CI enables **all** feature flags, including `ORY_PROJECT_TESTS_ENABLED`, on pull requests. Locally, `make test-acc-all` enables all flags **except** `ORY_PROJECT_TESTS_ENABLED` by default (project creation/deletion tests are excluded because they are slow and potentially destructive). To run those locally, set `ORY_PROJECT_TESTS_ENABLED=true` explicitly.
+
 #### Event Stream Tests
 
 Event stream tests have additional requirements beyond a feature flag because they interact with real AWS infrastructure:
@@ -208,7 +218,7 @@ To use a locally built provider, create a `~/.terraformrc` file:
 ```hcl
 provider_installation {
   dev_overrides {
-    "ory/terraform-provider-ory" = "/path/to/terraform-provider-ory"
+    "ory/ory" = "/path/to/terraform-provider-ory"
   }
   direct {}
 }
@@ -267,14 +277,14 @@ After editing templates, run `make format` to regenerate docs.
 
 ### Pre-Commit Checklist
 
-Run these checks locally before committing. They mirror what CI runs on every push.
+Run these checks locally before committing. They mirror what CI runs on every pull request.
 
 #### Required
 
 ```bash
 make build          # Verify the provider compiles
 make format         # Format code, tidy modules, regenerate docs, fix lint issues
-make test           # Run unit tests (no API calls needed)
+make test-short     # Run unit tests in short mode (matches CI)
 ```
 
 `make format` runs several tools in sequence:
@@ -287,7 +297,8 @@ make test           # Run unit tests (no API calls needed)
 #### Recommended
 
 ```bash
-make sec            # Run all security scans (govulncheck + gosec + gitleaks)
+make sec            # Run security scans (govulncheck + gosec + gitleaks)
+make sec-trivy      # Run trivy vulnerability scan (requires build first)
 make licenses       # Check dependency licenses
 ```
 
@@ -298,16 +309,18 @@ You can also run security scans individually:
 | `make sec-vuln` | govulncheck | Known Go vulnerabilities |
 | `make sec-gosec` | gosec | Go security patterns (injection, file traversal, etc.) |
 | `make sec-gitleaks` | gitleaks | Hardcoded secrets and credentials |
-| `make sec-trivy` | trivy | Vulnerability, secret, and misconfig scanning |
+| `make sec-trivy` | trivy | Vulnerability, secret, and misconfig scanning (not included in `make sec`) |
+
+> **Note:** `make sec-trivy` is **not** included in `make sec` — it must be run separately and requires a prior `make build`.
 
 #### Quick Reference
 
 ```bash
 # Minimum before committing:
-make build && make format && make test
+make build && make format && make test-short
 
 # Full CI-equivalent check:
-make build && make format && make test && make sec && make licenses
+make build && make format && make test-short && make sec && make sec-trivy && make licenses
 ```
 
 ### Code Style
@@ -332,7 +345,7 @@ docs: add algorithm guidance to JWK docs
 1. Fork the repository
 2. Create a feature branch from `main`
 3. Make your changes
-4. Run checks: `make build && make format && make test`
+4. Run checks: `make build && make format && make test-short`
 5. Submit a pull request using the PR template
 
 Please include:

README.md

@@ -44,7 +44,7 @@ A Terraform provider for managing [Ory Network](https://www.ory.sh/) resources u
 ## Requirements
 
 - [Terraform](https://www.terraform.io/downloads) >= 1.0
-- [Go](https://golang.org/doc/install) >= 1.21 (for building from source)
+- [Go](https://golang.org/doc/install) (see version in `go.mod`; for building from source)
 - An [Ory Network](https://console.ory.sh/) account
 
 ## Installation
@@ -302,22 +302,24 @@ Acceptance tests run against a **pre-created Ory project**. Copy `.env.example`
 cp .env.example .env
 ```
 
-At minimum you need:
+The `.env` file is gitignored and automatically loaded by `make` targets.
+
+**Required** (validated by `make env-check`):
 
 ```bash
-# Workspace credentials
 ORY_WORKSPACE_API_KEY=ory_wak_...
 ORY_WORKSPACE_ID=...
+```
+
+**Recommended** (needed by most resource tests):
 
-# Pre-created test project
+```bash
 ORY_PROJECT_ID=...
 ORY_PROJECT_SLUG=...
 ORY_PROJECT_API_KEY=ory_pat_...
 ORY_PROJECT_ENVIRONMENT=prod
 ```
 
-The `.env` file is gitignored and automatically loaded by `make` targets.
-
 ```bash
 make test-acc              # Standard acceptance tests
 make test-acc-verbose      # With debug logging
@@ -433,26 +435,26 @@ templates/
 
 ### Pre-Commit Checklist
 
-Run these checks locally before committing. They mirror what CI runs on every push.
+Run these checks locally before committing. They mirror what CI runs on every pull request.
 
 ```bash
 # Minimum before committing:
-make build && make format && make test
+make build && make format && make test-short
 
 # Full CI-equivalent check:
-make build && make format && make test && make sec && make licenses
+make build && make format && make test-short && make sec && make sec-trivy && make licenses
 ```
 
 `make format` runs several tools in sequence: `go fmt`, `gofmt -s`, `terraform fmt`, `go mod tidy`, `tfplugindocs generate`, and `golangci-lint --fix`.
 
 ### Security Scanning
 
 ```bash
-make sec            # Run all security scans
+make sec            # Run security scans (govulncheck + gosec + gitleaks)
 make sec-vuln       # govulncheck — known Go vulnerabilities
 make sec-gosec      # gosec — Go security patterns
 make sec-gitleaks   # gitleaks — hardcoded secrets
-make sec-trivy      # trivy — vulnerability and misconfig scanning
+make sec-trivy      # trivy — vulnerability and misconfig scanning (not included in `make sec`)
 ```
 
 ## Contributing
@@ -461,7 +463,7 @@ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed g
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Run checks: `make build && make format && make test`
+3. Run checks: `make build && make format && make test-short`
 4. Commit using [Conventional Commits](https://www.conventionalcommits.org/) format
 5. Open a Pull Request