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 ### 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 -**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 -**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 -**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.) - Still follow all database protocols (atomic changes, validation, etc.)
- **If modifying database schema:** Update local database after schema.sql changes (see Database Operations section) - **If modifying database schema:** Update local database after schema.sql changes (see Database Operations section)
- Still use Podman for all builds - 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) ### API Changes (Full-Stack Tasks Only)
- ✅ Include **Bruno OpenCollection YAML requests** with all API documentation - ✅ 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 - ✅ Maintain backward compatibility for mobile apps and external consumers
### Frontend & Styling ### Frontend & Styling
@@ -231,7 +231,7 @@ VERIFY → Compile successfully
| **Quick start/setup** | `README.md` | Installation, environment setup, first-run | | **Quick start/setup** | `README.md` | Installation, environment setup, first-run |
| **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices | | **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices |
| **Bug fixes** | Update relevant `docs/` only if user-visible | Clarifications, troubleshooting additions | | **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**: **Documentation Update Workflow**:
@@ -240,7 +240,7 @@ VERIFY → Compile successfully
3. **Update documentation** before or with code changes 3. **Update documentation** before or with code changes
4. **Verify documentation renders** at `/docs` endpoint 4. **Verify documentation renders** at `/docs` endpoint
5. **Test search** finds new/updated content 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>` 7. **Commit separately** with clear message: `docs: <description>`
**When in doubt**: **When in doubt**:
@@ -351,6 +351,7 @@ git checkout -- internal/handlers/auth.go
- [ ] API behavior → Update existing `docs/developer/api/` files - [ ] API behavior → Update existing `docs/developer/api/` files
- [ ] Breaking changes → Both `README.md` + relevant `docs/` - [ ] Breaking changes → Both `README.md` + relevant `docs/`
- [ ] Bruno OpenCollection YAML `.yml` files → Update/create alongside API changes - [ ] 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) ### During Schema Changes (Full-Stack Only)
@@ -377,6 +378,7 @@ git checkout -- internal/handlers/auth.go
### After API Changes ### After API Changes
- [ ] Create/update Bruno OpenCollection YAML requests - [ ] Create/update Bruno OpenCollection YAML requests
- [ ] Create/update Integration tests (cmd/server/tests)
- [ ] Test with no user context - [ ] Test with no user context
- [ ] Test with regular user context - [ ] Test with regular user context
- [ ] Test with admin context - [ ] Test with admin context
@@ -393,7 +395,7 @@ git checkout -- internal/handlers/auth.go
- [ ] Verify logical commit structure - [ ] Verify logical commit structure
- [ ] **Update documentation** (see Documentation section): - [ ] **Update documentation** (see Documentation section):
- [ ] User-facing changes → `docs/user/` - [ ] 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` - [ ] Setup/onboarding → `README.md`
- [ ] Development changes → `docs/contributing/` - [ ] Development changes → `docs/contributing/`
- [ ] **Verify docs render** at `/docs` endpoint - [ ] **Verify docs render** at `/docs` endpoint