From 8b49b058c11303956d987ff10cd4790bc8c676ea Mon Sep 17 00:00:00 2001 From: huytran2005 Date: Sat, 17 Oct 2026 17:22:22 +0700 Subject: [PATCH] [KAN-57] chore: establish engineering rules, PR templates, and validation workflows --- .github/PULL_REQUEST_TEMPLATE.md | 18 +++++ .github/rules/automation-policy.md | 98 ++++++++++++++++++++++++++ .github/workflows/pr-validation.yml | 68 ++++++++++++++++++ AGENTS.md | 104 ++++++++++++++++++++++++++++ CONTRIBUTING.md | 71 +++++++++++++++++++ 5 files changed, 359 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/rules/automation-policy.md create mode 100644 .github/workflows/pr-validation.yml create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..408cf2de --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,18 @@ +### Summary + + +### Changes + +- + +### Testing + +- + +### Jira + +- Jira Issue: [KAN-XXX](https://huytran20052022.atlassian.net/browse/KAN-XXX) + +### Notes + +- None diff --git a/.github/rules/automation-policy.md b/.github/rules/automation-policy.md new file mode 100644 index 00000000..a0a071a6 --- /dev/null +++ b/.github/rules/automation-policy.md @@ -0,0 +1,98 @@ +# Engineering Standards & Governance Policy + +This policy outlines the official working rules for Jira, Git, GitHub Pull Requests, GitHub Actions, testing, and AI-assisted development for the **Cruise Activity and Service Management System**. + +--- + +## 1. Jira Task & Subtask Rules + +### Hierarchy +- **Epic:** Major business capability (e.g. Shore Excursion Management, POS Cashless System, Passenger Mobile Portal). +- **Task / Story:** Deliverable functional unit (e.g. `KAN-185`: Implement Excursion Status Tracking). +- **Subtask:** Specific, actionable implementation or test step. + +### Subtask Structure for Stories +When breaking down a story, define relevant subtasks: +1. **Implementation:** Backend entity/DTO/service or Frontend UI components. +2. **Unit Testing:** Business rules, status transitions, or component tests. +3. **Integration Testing:** API endpoints, MockMvc, or E2E flows where applicable. +4. **Documentation & Validation:** OpenAPI/Swagger docs or validation suites when necessary. + +### Issue Lifecycle & Status Transitions +- `To Do` -> `In Progress` (when active branch and implementation starts). +- `In Progress` -> `In Review` (when Pull Request is created and CI is running). +- `In Review` -> `Done` (ONLY after PR is approved, passes all CI status checks, and is squashed/merged into `main`). +- **Never mark Done prematurely** while PR is still open or checks are pending. + +--- + +## 2. Git Branching & Protection Rules + +### Branch Standards +- `feat/KAN-xxx-short-description` +- `fix/KAN-xxx-short-description` +- `test/KAN-xxx-short-description` +- `docs/KAN-xxx-short-description` +- `refactor/KAN-xxx-short-description` +- `chore/KAN-xxx-short-description` + +### Branch Protection on `main` +- Direct commits to `main` are disabled. +- Require Pull Request before merging. +- Require Status Checks to pass before merging: + - PR Validation (`validate-pr`) + - CI Build & Test + - SonarCloud Quality Gate +- Require linear history via **Squash and merge**. + +--- + +## 3. Commit Standards + +- Format: `[KAN-xxx] (): ` +- Conventional types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`, `perf`, `ci`. +- Keep commits focused and atomic. +- Never commit secrets, credentials, or generated directories (`target/`, `node_modules/`, `dist/`). + +--- + +## 4. Pull Request Standards & Automation + +### PR Title +- Must match: `[KAN-xxx] type: concise description` +- Example: `[KAN-185] feat: build excursion status dashboard, schedule timing display, and component test suite` + +### PR Description +Must adhere to `.github/PULL_REQUEST_TEMPLATE.md`: +- `### Summary`: 1–3 clear sentences. +- `### Changes`: Bullet list of modifications. +- `### Testing`: Real test executions and exact counts/results. +- `### Jira`: Direct link to Jira issue (`https://huytran20052022.atlassian.net/browse/KAN-xxx`). +- `### Notes`: Architectural context, migrations, or `None`. + +### Validation Workflow (`pr-validation.yml`) +Runs automatically on every PR open/edit/synchronize to check: +1. Title adheres to regex. +2. Body does not contain literal `\n` or `\\n` escape sequences. +3. Required headings are present. +4. Jira issue key is present and not an unresolved placeholder like `KAN-XXX`. + +--- + +## 5. Testing & Quality Gates + +- Every backend change must include unit tests (`*UnitTest.java`) and integration tests (`*IntegrationTest.java`). +- Every frontend change must include Vitest component tests (`*.test.tsx`). +- No pull request shall be approved or merged if code coverage drops or if SonarCloud reports security or reliability bugs. + +--- + +## 6. AI-Assisted Development & Automated Remediation + +AI coding agents (Copilot, Jules, Gemini, Antigravity) must: +1. Analyze CI logs and pinpoint root causes. +2. Apply minimal, scoped fixes without refactoring unrelated code. +3. Run tests locally and verify 100% pass before pushing. +4. Never weaken or remove test assertions to pass CI artificially. +5. Prevent infinite retry loops. +6. Request human sign-off for critical operations (e.g., migrations, auth changes, payment logic). diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml new file mode 100644 index 00000000..243a9a70 --- /dev/null +++ b/.github/workflows/pr-validation.yml @@ -0,0 +1,68 @@ +name: Validate Pull Request + +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: + pull-requests: read + contents: read + +jobs: + validate-pr: + name: Validate PR Title & Format + runs-on: ubuntu-latest + steps: + - name: Validate PR Title Convention + uses: actions/github-script@v7 + with: + script: | + const title = context.payload.pull_request.title.trim(); + // Expected format: [KAN-xxx] type: concise description + const titleRegex = /^\[(KAN-\d+)\]\s+(feat|fix|test|docs|refactor|chore|perf|ci)(\([a-zA-Z0-9_\-]+\))?:\s+.+$/; + + if (!titleRegex.test(title)) { + core.setFailed( + `PR Title "${title}" does not match required format: [KAN-xxx] type: concise description\n` + + `Example: [KAN-185] feat: implement excursion status tracking` + ); + } else { + core.info(`PR Title is valid: ${title}`); + } + + - name: Validate PR Description Structure + uses: actions/github-script@v7 + with: + script: | + const body = context.payload.pull_request.body || ""; + + // 1. Check for literal escape sequences like \n or \n\n + if (/\\n/.test(body)) { + core.setFailed("PR body contains literal '\\n' escape sequences. Use real newline characters."); + } + + // 2. Check for required headings + const requiredSections = [ + "### Summary", + "### Changes", + "### Testing", + "### Jira" + ]; + + const missingSections = requiredSections.filter(sec => !body.includes(sec)); + if (missingSections.length > 0) { + core.setFailed(`PR description is missing required sections: ${missingSections.join(", ")}`); + } + + // 3. Check for Jira Key in body + const jiraRegex = /KAN-\d+/; + if (!jiraRegex.test(body)) { + core.setFailed("PR description must reference a valid Jira issue key (e.g. KAN-123)."); + } + + // 4. Check for unresolved placeholders + if (body.includes("KAN-XXX")) { + core.setFailed("PR description contains placeholder 'KAN-XXX'. Please replace it with the actual Jira issue key."); + } + + core.info("PR description structure passed all validation checks."); diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..7acfdc3f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,104 @@ +# AI Coding Agent & Contributor Directives (AGENTS.md) + +This repository (`Cruise-api`) contains the Spring Boot microservices backend for the **Cruise Activity and Service Management System**. +All AI coding agents (Claude, Copilot, Jules, Gemini, Antigravity, etc.) and human developers working in this repository must strictly adhere to the policies established in this document. + +--- + +## 1. Jira Project & Issue Key Rules + +- **Jira Project Key:** `KAN` (Domain: `https://huytran20052022.atlassian.net/`) +- **Hierarchy:** + - **Epic:** Major capability (e.g., Shore Excursion Management, POS Cashless System). + - **Story / Task:** Deliverable functional unit (e.g., `KAN-185`: Implement Excursion Status Tracking). + - **Subtask:** Specific, actionable implementation or test step (e.g., `KAN-187`: Transitions, `KAN-190`: Unit tests). +- **Rule of Record:** Every feature branch, commit message, and PR title MUST explicitly reference a valid Jira issue key (`KAN-xxx`). +- **Do Not Fabricate Keys:** Always verify the Jira issue key from the active user prompt or Jira API. +- **Completion Guarantee:** Merely pushing code or opening a PR does NOT mark a Jira task Done. An issue is only eligible for `Done` once CI passes, code review completes without blocking comments, and the PR is merged to `main`. + +--- + +## 2. Branching Strategy (GitHub Flow) + +- **Default & Protected Branch:** `main` (Strictly protected; NO direct pushes allowed). +- **Branch Naming Standard:** + - `feat/KAN-xxx-short-description` (New features / business logic) + - `fix/KAN-xxx-short-description` (Bug fixes / error corrections) + - `test/KAN-xxx-short-description` (Test suite additions / mock repairs) + - `docs/KAN-xxx-short-description` (Documentation updates) + - `refactor/KAN-xxx-short-description` (Code restructuring without behavior changes) + - `chore/KAN-xxx-short-description` (Build, dependency, or CI/CD workflow updates) +- **Scope:** + - Develop on one feature branch per parent story/deliverable. Related subtasks share the parent branch. + - Never stage or commit unrelated changes. + - Verify `git status` and working tree before creating commits. + +--- + +## 3. Commit Message Conventions + +Follow Conventional Commits with Jira issue reference: + +``` +[] (): + +[optional body explaining rationale] +``` + +### Commit Types: +- `feat`: New feature or endpoint. +- `fix`: Bug fix in logic or error handling. +- `test`: Unit or integration tests. +- `refactor`: Code improvements that neither fix bugs nor add features. +- `docs`: Documentation, README, or OpenAPI changes. +- `chore`: Maven pom, Docker, or GitHub Actions changes. + +### Commit Rules: +1. Reference the Jira issue key in every commit (e.g., `[KAN-185] feat: ...`). +2. Keep commits atomic, cohesive, and free of extraneous or generated files (`.class`, `target/`, IDE configs). +3. Never force-push (`git push --force`) to shared branches. + +--- + +## 4. Pull Request Standards & Title Format + +- **PR Title Format:** + ``` + [KAN-xxx] type: concise description + ``` + *Example:* `[KAN-185] feat: implement excursion status tracking and transition validation` +- **PR Description:** Must follow the repository PR template (`.github/PULL_REQUEST_TEMPLATE.md`), containing: + - Summary (1–3 sentences explaining the outcome). + - Changes made (bulleted list). + - Testing performed and verified evidence. + - Jira ticket link (`https://huytran20052022.atlassian.net/browse/KAN-xxx`). + - Risks and notes. +- **Validation:** + - Never submit raw escape sequences (`\n\n`) in PR markdown. + - Ensure all assertions, test names, and files changed match the actual git diff. + +--- + +## 5. Testing & Code Quality Gates + +- **Backend Stack:** Java 21/25 (LTS), Spring Boot 3.x, Maven, PostgreSQL, JaCoCo, SonarCloud. +- **Mandatory Local Verification:** + Before pushing, execute the verification command locally: + ```powershell + ./mvnw clean verify -DskipTests=false + ``` +- **Testing Requirements:** + - Unit tests for service layer business rules (`*UnitTest.java`). + - Integration tests using MockMvc or Testcontainers for API endpoints (`*IntegrationTest.java`). + - Never weaken assertions or delete tests simply to get a passing build. + - SonarCloud Quality Gate must remain **PASSED** (0 security vulnerabilities, 0 bugs, minimal code smells). + +--- + +## 6. AI-Assisted Remediation & Safety Guardrails + +When an AI agent is invoked to triage or repair a build/CI failure: +1. **Analyze Failure Logs:** Inspect compiler errors, Surefire XML reports, or SonarCloud findings. +2. **Minimal Patch Principle:** Apply targeted, minimal fixes within the authorized task scope. +3. **No Secret Exposure:** Never log, commit, or print tokens, private keys, or passwords. +4. **No Destructive Operations:** Do not drop database tables, delete git history, or bypass tests without explicit user consent. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..0c6cc133 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing to Cruise Activity & Service Management System (Backend API) + +Thank you for contributing! All team members and AI coding assistants must adhere to the engineering standards described here. + +--- + +## 1. Jira Ticket & Subtask Requirements + +- **Jira Instance:** `https://huytran20052022.atlassian.net/` | Project Key: `KAN` +- Every functional change must map to a Jira Story/Task. +- Complex stories should have subtasks covering: + 1. Implementation + 2. Unit Tests + 3. Integration Tests + 4. Documentation & Validation +- Jira issues must only be moved to `Done` after PR approval, passing CI, and merge to `main`. + +--- + +## 2. Git Workflow & Branching + +- We use **GitHub Flow**. +- Always branch off the latest `main`: + ```bash + git checkout main + git pull origin main + git checkout -b feat/KAN-xxx-feature-name + ``` +- Allowed branch prefixes: + - `feat/KAN-xxx-...` (Feature) + - `fix/KAN-xxx-...` (Bug fix) + - `test/KAN-xxx-...` (Testing) + - `docs/KAN-xxx-...` (Documentation) + - `refactor/KAN-xxx-...` (Refactoring) + - `chore/KAN-xxx-...` (CI/Build/Dependencies) +- **Direct push to `main` is strictly forbidden.** + +--- + +## 3. Commit Guidelines + +- Commit message structure: + ``` + [KAN-xxx] (): + ``` +- Use Conventional Commit types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`, `perf`. +- Do not commit sensitive credentials, keys, or build artifacts (`target/`, `.class`). + +--- + +## 4. Pull Request Requirements + +- PR Title format: `[KAN-xxx] type: concise description` +- Fill out all required sections in `.github/PULL_REQUEST_TEMPLATE.md`: + - `### Summary` + - `### Changes` + - `### Testing` + - `### Jira` + - `### Notes` +- Automated GitHub Actions validate the title and body format on every PR. +- Required checks (Build & Test, SonarCloud) must be green. + +--- + +## 5. Local Build & Test Verification + +Before submitting code, run: +```powershell +./mvnw clean verify -DskipTests=false +``` +All unit tests and integration tests must pass 100%.