rinafcode · RUKAYAT-CODER · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -90,7 +90,7 @@ module.exports = {
     'no-shadow': 'off',
     '@typescript-eslint/no-shadow': 'warn',
     'no-return-await': 'off',
-    '@typescript-eslint/return-await': ['warn', 'in-try-catch'],
+    '@typescript-eslint/return-await': 'off',
 
     // ── NestJS best practices ─────────────────────────────────────────────────
     '@typescript-eslint/no-unsafe-return': 'off',

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -28,54 +28,81 @@ Closes #N
 
 ---
 
-## Pre-merge checklist
+## Pre-merge checklist (required)
 
-**Branch**
+> **Do not remove items. Unchecked items without an explanation will block merge.**
 
-- [ ] Branch name follows `feature/issue-<N>-<slug>` convention
+**Branch & metadata**
+
+- [ ] Branch name follows `feature/issue-<N>-<slug>` / `fix/issue-<N>-<slug>` convention
 - [ ] Branch is up to date with the target branch (`develop` or `main`)
-- [ ] All commits follow the Conventional Commits format with issue reference
+- [ ] All commits and the PR title follow the Conventional Commits format with issue reference
 
-**Code quality** — run these locally and confirm they pass:
+**Code quality & tests**
 
 - [ ] `npm run lint:ci` — zero ESLint warnings
 - [ ] `npm run format:check` — Prettier reports no changes needed
 - [ ] `npm run typecheck` — zero TypeScript errors
 - [ ] `npm run test:ci` — all tests pass, coverage ≥ 70%
-
-**Testing**
-
 - [ ] New service methods have corresponding `.spec.ts` unit tests
 - [ ] New API endpoints are covered by at least one e2e test
-- [ ] No existing tests were deleted (if any were, explain below)
+- [ ] No existing tests were deleted (if any were, justification is provided in the PR description)
+
+**Error handling & NestJS best practices**
+
+- [ ] All new/updated DTOs use `class-validator` / `class-transformer` decorators and are wired through NestJS pipes (e.g. global `ValidationPipe` or explicit)
+- [ ] All controller entry points validate external input at the boundary (no unvalidated raw `any`/`unknown` reaching the domain)
+- [ ] Controllers/services throw appropriate NestJS HTTP exceptions (e.g. `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`) instead of generic `Error`
+- [ ] Any new error shapes are handled by existing exception filters or the filters have been updated accordingly
+- [ ] Logging goes through the shared logging abstraction (e.g. Nest `Logger` or central logger service) with meaningful, structured messages
+- [ ] Authentication/authorization guards (e.g. `AuthGuard`, role/permissions guards, custom guards) are applied to all new/modified endpoints where appropriate
+- [ ] If an endpoint is intentionally public, this is explicitly mentioned in the PR description with rationale
 
-**Documentation**
+**API documentation / Swagger**
 
-- [ ] JSDoc comments added to all new public service methods
-- [ ] Swagger / OpenAPI decorators added for all new controller endpoints
-- [ ] `README.md` or `CONTRIBUTING.md` updated if this changes contributor workflow
+- [ ] Swagger / OpenAPI decorators are added or updated for all new/changed controller endpoints (including DTOs, responses, and error schemas)
+- [ ] I have started the app locally and confirmed the `/api` (or Swagger UI) reflects new/changed endpoints correctly
+- [ ] If there are **no** API surface changes, this is explicitly stated in the PR description
 
 **Breaking changes**
 
 - [ ] This PR does **not** introduce a breaking API change
-- [ ] OR: this PR introduces a breaking change and it is documented below
+- [ ] OR: this PR introduces a breaking change and it is documented below, with migration notes
 
 ---
 
 ## Breaking change description (if applicable)
 
 <!-- If you checked "Breaking change" above, describe what changes and how consumers should migrate. -->
+<!-- Include any feature flags, deprecation periods, or follow-up tasks. -->
 <!-- Delete this section if not applicable. -->
 
 ---
 
-## Testing notes
+## Test evidence (required)
 
-<!-- Describe how reviewers can manually verify this change if needed. -->
-<!-- Include example curl commands, Swagger routes, or Jest test names to run. -->
+<!-- Paste concrete evidence that the change was tested.  -->
+<!-- Examples: exact npm scripts run with ✅ results, curl/Postman examples, screenshots of Swagger, Jest test names, etc. -->
+
+**Commands run locally**
+
+```text
+# Example (edit as needed)
+npm run lint:ci
+npm run format:check
+npm run typecheck
+npm run test:ci
+```
+
+**Manual / API verification**
+
+```text
+# Example: describe manual tests, curl commands, or Postman collections used
+```
 
 ---
 
 ## Screenshots / recordings (if applicable)
 
-<!-- Delete if not applicable -->
+<!-- Add Swagger screenshots, error responses, or UI flows if they help reviewers. -->
+<!-- Delete this section if not applicable. -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -235,39 +235,44 @@ Every PR must satisfy **all** of the following before a reviewer will read the c
 
 ### Checklist (enforced via PR template)
 
-```
-Linked issue
-  [ ] This PR closes #<issue-number>
-
-Branch
-  [ ] Branch is up to date with the target branch (develop or main)
-  [ ] Branch name follows the convention: feature/issue-<N>-<slug>
-
-Commits
-  [ ] All commits follow the Conventional Commits format
-  [ ] Each commit references the issue number
-
-Code quality
-  [ ] npm run lint:ci passes with zero warnings
-  [ ] npm run format:check passes
-  [ ] npm run typecheck passes with zero errors
-  [ ] All new code has unit tests
-  [ ] npm run test:ci passes and coverage threshold is maintained
-
-Testing
-  [ ] New service methods have corresponding .spec.ts tests
-  [ ] New API endpoints are covered by at least one e2e test
-  [ ] No existing tests were deleted without justification
-
-Documentation
-  [ ] JSDoc added for all public service methods
-  [ ] Swagger decorators added for all new controller endpoints
-  [ ] README / CONTRIBUTING updated if behaviour changes
-
-Breaking changes
-  [ ] If this PR introduces a breaking API change, it is noted
-      in the PR description and the issue is flagged "breaking-change"
-```
+The GitHub pull request template (`.github/pull_request_template.md`) is **required for all contributors**.  
+Do not delete sections or checklist items. Unchecked items without a clear explanation in the PR description are treated as **merge blockers**.
+
+Key items the template enforces:
+
+- **Linked issue**
+  - [ ] This PR closes `#<issue-number>` using `Closes #<N>` / `Fixes #<N>` / `Resolves #<N>`
+
+- **Branch & commits**
+  - [ ] Branch is up to date with the target branch (`develop` or `main`)
+  - [ ] Branch name follows the convention: `feature/issue-<N>-<slug>` / `fix/issue-<N>-<slug>` / `hotfix/issue-<N>-<slug>`
+  - [ ] All commits and the PR title follow the Conventional Commits format and include the issue number
+
+- **Code quality & tests**
+  - [ ] `npm run lint:ci` passes with zero warnings
+  - [ ] `npm run format:check` passes
+  - [ ] `npm run typecheck` passes with zero errors
+  - [ ] `npm run test:ci` passes and coverage threshold is maintained
+  - [ ] All new code paths have appropriate unit and/or e2e tests
+
+- **Error handling & NestJS best practices**
+  - [ ] DTOs use `class-validator` / `class-transformer` and are wired through NestJS validation pipes
+  - [ ] Inputs are validated at controller/module boundaries (no unvalidated raw payloads reaching services)
+  - [ ] Proper NestJS HTTP exceptions are thrown instead of generic `Error`
+  - [ ] Logging uses the shared logger with meaningful, structured messages
+  - [ ] Guards (auth/role/permission or custom) protect all endpoints that require authentication/authorization
+
+- **Documentation / Swagger**
+  - [ ] Swagger / OpenAPI decorators are present and updated for all new/changed endpoints, including error responses
+  - [ ] The author has verified locally that Swagger (e.g. `/api`) reflects the changes
+  - [ ] `README.md` or `CONTRIBUTING.md` is updated if contributor workflow or API behaviour changes
+
+- **Breaking changes**
+  - [ ] Any breaking API change is explicitly called out in the dedicated template section
+  - [ ] The linked issue is flagged with an appropriate label (for example, `breaking-change`)
+
+In addition, the template includes a **Test evidence** section where authors must paste the exact commands run and any relevant manual/API verification steps.  
+PRs without concrete test evidence will be asked for changes and are not eligible for approval.
 
 ### PR title format
 
@@ -323,6 +328,7 @@ Reviewers are expected to check:
 - Security — no secrets in code, input validation present, auth guards applied
 - Test coverage — all new paths have tests
 - API contract — no silent breaking changes to existing endpoints
+- Error handling — DTO validation, proper NestJS HTTP exceptions, logging via the shared logger, guards/filters applied consistently
 - Module boundaries — NestJS dependency injection used correctly
 - Performance — no N+1 queries, no unbounded loops on collections from DB
 

diff --git a/commitlint.config.cjs b/commitlint.config.cjs
@@ -0,0 +1,5 @@
+/** @type {import('@commitlint/types').UserConfig} */
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+};
+