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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user