Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
### Summary
<!-- Explain the purpose and outcome of the change in 1–3 sentences. -->

### Changes
<!-- List the important implementation changes as bullet points. -->
-

### Testing
<!-- List the tests and validation checks actually executed, including their results. -->
-

### Jira
<!-- Include the correct Jira issue key and link when the URL is available. -->
- Jira Issue: [KAN-XXX](https://huytran20052022.atlassian.net/browse/KAN-XXX)

### Notes
<!-- Mention relevant limitations, breaking changes, migration requirements, or risks. If none apply, state that no additional notes are required. -->
- None
98 changes: 98 additions & 0 deletions .github/rules/automation-policy.md
Original file line number Diff line number Diff line change
@@ -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] <type>(<scope>): <concise description>`
- 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).
68 changes: 68 additions & 0 deletions .github/workflows/pr-validation.yml
Original file line number Diff line number Diff line change
@@ -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.");
104 changes: 104 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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:

```
[<JIRA-KEY>] <type>(<scope>): <concise description in imperative mood>

[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.
71 changes: 71 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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] <type>(<scope>): <imperative summary>
```
- 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%.
Loading