docs: clarify testing and API documentation requirements in PROJECT_GUIDELINES.md

Minor updates to clarify project guidelines:

Testing section:
- Correct test_helpers.go filename reference (test_helpers_test.go)
- Clarify integration test requirements (cmd/server/tests) vs all tests

API Changes section:
- Change 'Bruno tests' to 'Bruno requests' for clarity
- Specify integration test files (cmd/server/tests) in documentation workflow

Documentation section:
- Update 'Bruno OpenCollection YAML tests' to 'Bruno OpenCollection YAML requests'

These are documentation clarifications only - no code changes.
Ensures consistency between guidelines and actual project structure.
This commit is contained in:
2026-03-06 22:26:37 -05:00
parent 85a11549bf
commit df132c8010
+8 -6
View File
@@ -16,7 +16,7 @@
### Testing
-**ALWAYS use `setupTestServer()` helper from `cmd/server/tests/test_helpers.go`**
-**ALWAYS use `setupTestServer()` helper from `cmd/server/tests/test_helpers_test.go`**
-**Share one test setup across all subtests** - call `setupTestServer()` once at test function level, not per subtest
-**Prefer table-driven tests** - use `t.Run()` with test cases instead of duplicate test functions
-**Configure database pools efficiently** - use `max_conns=1` for test pools (via `pgxpool.ParseConfig()`) to prevent connection exhaustion
@@ -119,7 +119,7 @@ VERIFY → Compile successfully
- Still follow all database protocols (atomic changes, validation, etc.)
- **If modifying database schema:** Update local database after schema.sql changes (see Database Operations section)
- Still use Podman for all builds
- Still include Bruno tests for API changes
- Still include Bruno requests for API changes
---
@@ -150,7 +150,7 @@ VERIFY → Compile successfully
### API Changes (Full-Stack Tasks Only)
- ✅ Include **Bruno OpenCollection YAML requests** with all API documentation
- ✅ Tests must be **comprehensive and cover three contexts**: no user, user, and admin
- ✅ Integration Tests (cmd/server/tests) must be **comprehensive and cover three contexts**: no user, user, and admin
- ✅ Maintain backward compatibility for mobile apps and external consumers
### Frontend & Styling
@@ -231,7 +231,7 @@ VERIFY → Compile successfully
| **Quick start/setup** | `README.md` | Installation, environment setup, first-run |
| **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices |
| **Bug fixes** | Update relevant `docs/` only if user-visible | Clarifications, troubleshooting additions |
| **Bruno OpenCollection YAML tests** | `.yml` files in bruno folder in appropriate folder/sub-folder | API contract testing, examples |
| **Bruno OpenCollection YAML requests** | `.yml` files in bruno folder in appropriate folder/sub-folder | API contract testing, examples |
**Documentation Update Workflow**:
@@ -240,7 +240,7 @@ VERIFY → Compile successfully
3. **Update documentation** before or with code changes
4. **Verify documentation renders** at `/docs` endpoint
5. **Test search** finds new/updated content
6. **For API changes**: Update both `docs/developer/api/` files AND Bruno OpenCollection YAML `.yml` files
6. **For API changes**: Update both `docs/developer/api/` files, integration test files (cmd/server/tests) AND Bruno OpenCollection YAML `.yml` files
7. **Commit separately** with clear message: `docs: <description>`
**When in doubt**:
@@ -351,6 +351,7 @@ git checkout -- internal/handlers/auth.go
- [ ] API behavior → Update existing `docs/developer/api/` files
- [ ] Breaking changes → Both `README.md` + relevant `docs/`
- [ ] Bruno OpenCollection YAML `.yml` files → Update/create alongside API changes
- [ ] Integration tests (cmd/server/tests) → Update/create alongside API changes
### During Schema Changes (Full-Stack Only)
@@ -377,6 +378,7 @@ git checkout -- internal/handlers/auth.go
### After API Changes
- [ ] Create/update Bruno OpenCollection YAML requests
- [ ] Create/update Integration tests (cmd/server/tests)
- [ ] Test with no user context
- [ ] Test with regular user context
- [ ] Test with admin context
@@ -393,7 +395,7 @@ git checkout -- internal/handlers/auth.go
- [ ] Verify logical commit structure
- [ ] **Update documentation** (see Documentation section):
- [ ] User-facing changes → `docs/user/`
- [ ] API changes → `docs/developer/api/` + Bruno OpenCollection YAML `.yml` files
- [ ] API changes → `docs/developer/api/` + Integration tests + Bruno OpenCollection YAML `.yml` files
- [ ] Setup/onboarding → `README.md`
- [ ] Development changes → `docs/contributing/`
- [ ] **Verify docs render** at `/docs` endpoint