desktop-team-doc 0.1.0

package/content/docs/instructions/coding-conventions/team-wide.md

@@ -0,0 +1,176 @@
+# Team-wide Coding Conventions
+
+*Last Updated: 2025-10-14*
+
+This document outlines the coding conventions that apply to all Desktop Team projects across all programming languages.
+
+## Commenting Policy: Minimalist, Purposeful, and Agent-Aware
+
+### Core Principle: Code Should Be Self-Documenting
+
+Prioritize clear naming, logical structure, and breaking down complexity over adding comments.
+
+### NO REDUNDANT COMMENTS
+
+Absolutely do not add comments that simply restate what a line or block of code obviously does in plain language. This applies especially to comments that merely translate code to English.
+
+### EXPLAIN 'WHY', NOT 'WHAT'
+
+If an inline comment is necessary, it MUST explain the reasoning, intent, or trade-offs behind a non-obvious piece of code, not describe the operation itself.
+
+**Good Example:**
+
+```cpp
+// Using a loop here due to X library's lack of batch processing for Y.
+```
+
+**Bad Example:**
+
+```cpp
+// Loop through the items.
+```
+
+### AVOID COMMENT 'NOISE'
+
+* Do not add decorative comment blocks (e.g., `/*** Section ***/`).
+* Do not comment obvious sections or self-explanatory code.
+* Avoid placeholder comments like `# TODO: Add comments` or `# Further explanation needed`.
+
+### PERMITTED & CONCISE COMMENTS
+
+* Explaining complex algorithms or business logic (high-level overview, not line-by-line).
+* Documenting non-obvious choices or workarounds for external issues/bugs.
+* `TODO`/`FIXME` notes: Must be actionable and ideally include a JIRA ticket or owner.
+* Conciseness is Key: Even permitted comments should be as brief as possible while conveying the necessary information.
+
+### AGENT-SPECIFIC GUIDANCE (For AI Code Generation/Modification)
+
+* **Assume Minimal Comments First**: When generating or modifying code, agents should default to adding no comments unless explicitly justified by the rules above (e.g., a non-obvious 'why').
+* **Review Agent-Added Comments**: Human reviewers should be particularly critical of comments added by agents, ensuring they are not just descriptive paraphrases of the code.
+* **Shell Script Comments**: For shell scripts, comments are permissible to explain complex command pipelines, non-obvious flags, or the purpose of a sequence of commands if it's not immediately clear from the commands themselves. However, avoid commenting simple, standard commands.
+  * Good Shell Example: `# Ensure script exits if any command fails` (before `set -e`)
+  * Bad Shell Example: `# List files` (before `ls -la`)
+
+### Header Comments
+
+File-level header comments (explaining the purpose of a file/module) are generally acceptable if they provide a high-level overview not immediately obvious from the filename or its contents. Keep them brief.
+
+---
+
+## General Formatting Principles
+
+### Universal Formatting Rules
+
+* Strive for consistent code formatting across all languages to enhance readability and maintainability.
+* Specific formatting tools and configurations (e.g., `.clang-format` for C++, Prettier/ESLint for Frontend) are detailed in the language-specific guidelines.
+* **As a universal rule:**
+  * Do not add indentation (spaces) to empty lines.
+  * Avoid all trailing whitespace on any line.
+
+---
+
+## Naming Conventions
+
+### Variables and Functions
+- Use camelCase for variable and function names
+- Use descriptive names that clearly indicate purpose
+- Avoid abbreviations unless widely understood
+- Boolean variables should start with "is", "has", or "should"
+
+### Classes and Interfaces
+- Use PascalCase for class and interface names
+- Class names should be nouns or noun phrases
+- Interface names should be adjectives or nouns prefixed with "I"
+
+### Constants
+- Use UPPER_SNAKE_CASE for constants
+- Define constants at the top of the file or in a dedicated constants file
+
+### File Names
+- Use kebab-case for file names
+- Match file names to the primary class or function they contain
+- Use consistent extensions (.ts, .cpp, etc.)
+
+## Code Formatting
+
+### Indentation
+- Use 2 spaces for indentation (not tabs)
+- Maintain consistent indentation throughout the codebase
+
+### Line Length
+- Maximum line length: 100 characters
+- Break long lines at logical points
+
+### Braces
+- Opening braces on the same line as the statement
+- Closing braces on their own line
+- Always use braces for control structures, even for single-line blocks
+
+### Spacing
+- One space after keywords (if, for, while, etc.)
+- No space between function name and parentheses
+- One space around operators (=, +, -, etc.)
+- No trailing whitespace
+
+## Documentation
+
+### Comments
+- Use JSDoc/Doxygen style for function and class documentation
+- Comment complex algorithms and business logic
+- Avoid obvious comments that duplicate code
+- Keep comments up-to-date with code changes
+
+### README Files
+- Each project should have a README.md file
+- Include setup instructions, dependencies, and usage examples
+- Document any non-standard configurations
+
+## Common Patterns and Anti-patterns
+
+### Patterns to Follow
+- Dependency injection for better testability
+- Early returns to reduce nesting
+- Error handling with appropriate logging
+- Immutable data structures where possible
+
+### Anti-patterns to Avoid
+- Global state
+- Deep nesting (more than 3 levels)
+- Magic numbers (use named constants)
+- Commented-out code (remove or use version control)
+- Duplicate code (extract to functions/utilities)
+
+## Language-specific Guidelines
+
+For detailed language-specific coding standards, see:
+
+* [C++ Coding Standards](./cpp.md) - C++ specific rules and best practices
+* [Frontend Coding Standards](./frontend.md) - React/TypeScript/JavaScript frontend development
+
+### Language-Specific Exceptions to Team-Wide Standards
+
+Some languages have established conventions that differ from team-wide defaults. These exceptions are documented in their respective language-specific guides and take precedence for that language:
+
+#### C++ Exceptions
+
+C++ projects follow `.clang-format` configuration which differs from team-wide defaults in these areas:
+
+* **Indentation**: 4 spaces (team-wide default: 2 spaces)
+* **Function Braces**: Opening brace on separate line (team-wide default: same line)
+* **Constant Naming**: `kCamelCase` prefix (team-wide default: `UPPER_SNAKE_CASE`)
+* **Pointer Alignment**: Right-aligned `int *ptr` (team-wide default: unspecified)
+
+See [C++ Coding Standards](./cpp.md) for complete details.
+
+## Linting and Formatting
+
+* **Frontend (React/TypeScript/JavaScript)**: Use ESLint and Prettier (see [Frontend Coding Standards](./frontend.md))
+* **TypeScript/JavaScript**: Use ESLint and Prettier
+* **C++**: Use clang-format with project configuration
+* Configure IDE to format on save
+* Run linters as part of CI/CD pipeline
+
+## Related Documentation
+
+* [Code Review Process](../workflows/code-review.md) - How to review code against these standards
+* [Git Commit Convention](../workflows/git-commit.md) - How to write commit messages

package/content/docs/instructions/workflows/code-review.md

@@ -0,0 +1,451 @@
+# Team-wide Code Review Guidelines
+
+Last Updated: 2025-10-16
+
+This document outlines the code review process and guidelines for all Desktop Team projects on GitHub.
+
+## Code Review Checklist
+
+### Task Completion
+
+- [ ] Implements requirements from JIRA ticket (verify ticket description and acceptance criteria)
+- [ ] Resolves all issues mentioned in the JIRA ticket
+- [ ] All acceptance criteria are met
+- [ ] Testing scenarios from ticket are covered
+
+### Commit Quality
+
+- [ ] Follows team git commit convention: `<type> BFD-<issue-number>: <subject>`
+- [ ] Commit messages are clear and accurately describe changes
+- [ ] Commit message explains "why", not just "what"
+- [ ] No unnecessary merge commits (use rebase when appropriate)
+- [ ] Each commit represents a logical unit of work
+
+### Functionality
+
+- [ ] Code works as expected and meets requirements
+- [ ] Edge cases are handled appropriately
+- [ ] Error handling is implemented correctly with proper logging
+- [ ] Performance considerations are addressed
+- [ ] No potential crashes or logic errors
+
+### Code Quality
+
+- [ ] Follows team coding style guidelines (see [Coding Conventions Reference](#coding-conventions-reference))
+- [ ] No code smells (duplicated code, overly complex methods)
+- [ ] Appropriate abstractions and design patterns
+- [ ] Maintainable and readable code
+- [ ] No deep nesting (max 3 levels)
+- [ ] No magic numbers (use named constants)
+
+### Commenting Policy (Critical)
+
+- [ ] **NO redundant comments** that restate what code obviously does
+- [ ] Comments explain "WHY", not "WHAT"
+- [ ] No decorative comment blocks or placeholder comments
+- [ ] TODOs/FIXMEs include actionable notes and JIRA tickets
+- [ ] Comments are concise and purposeful
+- [ ] Code is self-documenting through clear naming and structure
+
+### Naming Conventions
+
+- [ ] Variables/functions use proper casing (camelCase for TS/JS, per language standards)
+- [ ] Classes/interfaces use PascalCase
+- [ ] Constants properly formatted (UPPER_SNAKE_CASE for TS/JS, kCamelCase for C++)
+- [ ] Boolean variables start with "is", "has", or "should"
+- [ ] Names are descriptive and avoid unclear abbreviations
+- [ ] File names follow conventions (kebab-case for TS/JS, PascalCase for C++)
+
+### Formatting
+
+- [ ] Indentation correct (2 spaces for TS/JS, 4 spaces for C++)
+- [ ] Line length under limit (100 chars for C++, 120 chars for frontend)
+- [ ] Braces used for all control structures (even single-line)
+- [ ] No trailing whitespace
+- [ ] No indentation on empty lines
+- [ ] Passes linter checks (ESLint/Prettier for frontend, clang-format for C++)
+
+### Testing
+
+- [ ] Unit tests cover critical functionality
+- [ ] Tests are meaningful and not just for coverage
+- [ ] Edge cases are tested
+- [ ] Mocks and test doubles are used appropriately
+- [ ] Tests follow testing best practices (test behavior, not implementation)
+
+### Documentation
+
+- [ ] README and project documentation updated if needed
+- [ ] API documentation complete for public interfaces
+- [ ] Complex algorithms include high-level overview comments (not line-by-line)
+- [ ] Non-obvious design choices are documented
+
+### Security
+
+- [ ] No obvious security vulnerabilities
+- [ ] Sensitive data is handled securely
+- [ ] Input validation is implemented
+- [ ] Authentication and authorization checks are in place
+- [ ] No hardcoded credentials or secrets
+
+### Architecture & Patterns
+
+- [ ] Follows established architectural patterns from knowledge base
+- [ ] Consistent with existing codebase patterns
+- [ ] No violations of dependency injection principles
+- [ ] Proper separation of concerns
+- [ ] Cross-references knowledge base for affected components
+
+### Frontend-Specific (React/TypeScript)
+
+- [ ] Components follow proper structure (imports, types, hooks, handlers, render)
+- [ ] State management: Redux 或 Local State；不新增 Zustand
+- [ ] Props are properly typed with interfaces
+- [ ] Always use braces for functions and control statements
+- [ ] Use `axios` for API calls (exception: XMLHttpRequest for native commands)
+- [ ] Avoid indiscriminate props spreading
+- [ ] Use `twMerge` for Tailwind class merging
+- [ ] Path aliases use `@/src/` pattern
+- [ ] Custom hooks start with `use` prefix
+- [ ] No `any` types (use specific types or `unknown`)
+
+### C++-Specific
+
+- [ ] Follows `.clang-format` configuration exactly
+- [ ] Smart pointers used for ownership management
+- [ ] Lambda capture lists are explicit
+- [ ] Auto with trailing return type syntax: `auto func() -> ReturnType`
+- [ ] Class members end with underscore, struct members do not
+- [ ] Header guards use `#pragma once`
+- [ ] Pointer alignment is right-aligned (`int *ptr`)
+
+## Review Process Workflow on GitHub
+
+### 1. Preparation (Author)
+
+- Create a pull request (PR) on GitHub
+- Link JIRA ticket in PR description (use "Fixes BFD-XXX" or "Resolves BFD-XXX")
+- Assign appropriate reviewers
+- Provide context and testing instructions in PR description
+- Ensure PR title follows format: `<type> BFD-<issue-number>: <subject>`
+- Add appropriate labels (bug, enhancement, documentation, etc.)
+
+### 2. Initial Review (Reviewer)
+
+- Review code changes within expected time frame (see [Time Expectations](#time-expectations))
+- Check out the branch locally if needed for testing
+- Use the review checklist above systematically
+- Add review comments directly on specific code lines in GitHub
+- Provide constructive feedback with clear explanations
+- Reference knowledge base when applicable
+- Mark conversations as resolved only when issue is addressed
+
+### 3. Discussion
+
+- Author responds to all feedback
+- Discussions happen in PR comments (use GitHub's threaded conversations)
+- Complex issues may require video calls or pair programming
+- Tag reviewers with @mention when clarification is needed
+- Use "Request changes" for blocking issues, "Comment" for suggestions
+
+### 4. Revisions (Author)
+
+- Make requested changes in new commits (don't force-push during review)
+- Respond to all comments explaining changes or providing rationale
+- Mark conversations as resolved after addressing
+- Request re-review from reviewers when ready
+- Update PR description if scope changes
+
+### 5. Approval (Reviewer)
+
+- Re-review changes after author updates
+- Approve when all blocking issues are addressed
+- Required number of approvals must be met (see [Required Approvals](#required-approvals))
+- All CI/CD checks must pass (build, tests, linters)
+- All conversations should be resolved
+
+### 6. Merge (Author or Tech Lead)
+
+- Ensure all approvals are obtained
+- Verify CI/CD pipeline is green
+- Use appropriate merge strategy:
+  - **Squash and merge** for feature branches with many small commits
+  - **Rebase and merge** for clean commit history
+  - **Merge commit** when preserving branch history is important
+- Delete source branch after merge
+- Verify JIRA ticket is automatically updated/closed
+- Monitor deployment if auto-deploy is enabled
+
+## Systematic Review Process
+
+For thorough code reviews, follow this systematic approach:
+
+### Phase 1: Context Understanding
+
+1. **Read JIRA Ticket**
+   - Understand requirements and acceptance criteria
+   - Note specific testing scenarios
+   - Check for architectural decisions or constraints
+
+2. **Review PR Description**
+   - Understand author's approach and reasoning
+   - Note any specific areas author flagged for attention
+   - Check for related PRs or dependencies
+
+3. **Check Commit History**
+   - Review commit messages for clarity
+   - Understand logical progression of changes
+   - Verify each commit is atomic and follows conventions
+
+### Phase 2: Code Analysis
+
+1. **Examine Diff Summary**
+   - Get overview of all changed files
+   - Identify scope and impact of changes
+   - Check for unexpected file changes
+
+2. **Review Files Systematically**
+   - Start with core logic files (header → source, core → peripheral)
+   - Check test files for adequate coverage
+   - Review configuration or build file changes
+   - Examine documentation updates
+
+3. **Deep Dive Analysis**
+   - Check against coding standards and conventions
+   - Verify logic correctness and edge case handling
+   - Look for potential performance issues
+   - Check for security vulnerabilities
+   - Cross-reference with knowledge base patterns
+
+### Phase 3: Holistic Review
+
+1. **Test Coverage**
+   - Verify tests exist for new functionality
+   - Check if edge cases are tested
+   - Ensure tests are meaningful
+
+2. **Architecture Consistency**
+   - Verify changes align with existing patterns
+   - Check if new patterns are documented
+   - Ensure proper separation of concerns
+
+3. **Documentation**
+   - Verify README or docs are updated if needed
+   - Check if complex logic has appropriate comments
+   - Ensure API changes are documented
+
+### Phase 4: Providing Feedback
+
+1. **Categorize Comments**
+   - **Blocking**: Must be fixed before merge (security, bugs, violations)
+   - **Important**: Should be addressed (best practices, maintainability)
+   - **Suggestion**: Nice to have (optimizations, alternative approaches)
+
+2. **Write Clear Comments**
+   - Be specific about the issue
+   - Explain WHY, not just WHAT
+   - Suggest concrete solutions when possible
+   - Reference documentation or standards
+   - Use GitHub's suggestion feature for simple fixes
+
+3. **Provide Summary**
+   - Give overall assessment
+   - Highlight good practices
+   - Summarize key concerns
+   - Suggest next steps
+
+## Feedback Guidelines
+
+### For Reviewers
+
+- Be specific and clear about issues with file paths and line numbers
+- Explain why a change is needed, not just what to change
+- Suggest solutions when possible with code examples
+- Distinguish between blocking issues and suggestions
+- Acknowledge good code and practices
+- Be timely with reviews (see [Time Expectations](#time-expectations))
+- Use a constructive and respectful tone
+- Reference relevant documentation or standards
+- Avoid redundancy - check if others already raised the same point
+
+### For Authors
+
+- Be open to feedback and assume good intent
+- Explain design decisions when necessary
+- Ask for clarification if feedback is unclear
+- Address all comments before requesting re-review
+- Thank reviewers for their time and input
+- Don't take criticism personally
+- If you disagree, explain your reasoning respectfully
+- Update code and respond to comments promptly
+
+## Required Approvals
+
+### Standard Changes
+
+- At least **one approval** from a team member
+- Changes affecting multiple components require approval from each component owner
+- All automated checks must pass (CI/CD, tests, linters)
+
+### Critical Changes
+
+- At least **two approvals**, including one senior developer
+- Changes to core functionality require approval from the technical lead
+- Security-related changes require approval from the security team
+- Database schema changes require DBA review
+
+### Documentation Changes
+
+- One approval from a team member
+- Major documentation changes require approval from the technical writer or documentation owner
+
+## Time Expectations
+
+- **Small changes (< 200 lines)**: Review within 24 hours
+- **Medium changes (200-1000 lines)**: Review within 48 hours
+- **Large changes (> 1000 lines)**: Break into smaller PRs when possible, otherwise allow up to 72 hours
+
+**Note**: Authors should break down large features into smaller, reviewable PRs. If a PR exceeds 1000 lines, consider whether it can be split into logical increments.
+
+## Using GitHub CLI for Reviews
+
+You can use the GitHub CLI (`gh`) for efficient PR reviews:
+
+```bash
+# View PR details
+gh pr view <PR-number>
+
+# Check out PR branch locally
+gh pr checkout <PR-number>
+
+# List all open PRs
+gh pr list
+
+# Add review comment
+gh pr review <PR-number> --comment -b "Review comments"
+
+# Approve PR
+gh pr review <PR-number> --approve
+
+# Request changes
+gh pr review <PR-number> --request-changes -b "Changes needed"
+
+# Check PR status and checks
+gh pr checks <PR-number>
+```
+
+## Commit-by-Commit Review
+
+For complex PRs, reviewers may request a commit-by-commit walkthrough:
+
+1. **Review Each Commit Individually**
+   - Examine what each commit changes
+   - Verify commit message accurately describes changes
+   - Check that each commit is logical and atomic
+
+2. **Check Commit Progression**
+   - Ensure commits build upon each other logically
+   - Verify no "fix previous commit" commits (should be squashed)
+   - Check that test commits come with implementation commits
+
+3. **Provide Targeted Feedback**
+   - Comment on specific commits when issues are introduced
+   - Help author understand where to refactor
+   - Guide on commit organization for future PRs
+
+## Handling Disagreements
+
+1. **Discuss in PR comments** with clear reasoning and references to standards
+2. **If unresolved**, schedule a short meeting with relevant stakeholders
+3. **If still unresolved**, escalate to the technical lead for final decision
+4. **Document the decision** and reasoning in the PR comments
+5. **Update documentation** if the decision affects team standards
+
+## Common Review Pitfalls to Avoid
+
+### Pitfalls for Reviewers
+
+- ❌ Nitpicking on style (should be caught by linters)
+- ❌ Requesting changes without explanation
+- ❌ Being vague ("this could be better")
+- ❌ Reviewing entire PR in one massive comment
+- ❌ Not testing changes locally when needed
+- ❌ Ignoring PR for days
+
+### Pitfalls for Authors
+
+- ❌ Getting defensive about feedback
+- ❌ Making changes without explaining why
+- ❌ Marking conversations as resolved before addressing
+- ❌ Force-pushing during active review
+- ❌ Creating PRs that are too large
+- ❌ Not responding to comments
+
+## Coding Conventions Reference
+
+### Quick Reference by Language
+
+#### TypeScript/JavaScript (Frontend)
+
+- Indentation: 2 spaces
+- Line length: 120 characters
+- Naming: camelCase (variables/functions), PascalCase (components/classes)
+- Constants: UPPER_SNAKE_CASE
+- Files: kebab-case.tsx
+- Comments: Explain "why", not "what"
+- Linter: ESLint + Prettier
+
+#### C++ (Native)
+
+- Indentation: 4 spaces
+- Line length: 100 characters
+- Naming: camelCase (variables), PascalCase (classes), kCamelCase (constants)
+- Class members: trailing underscore (camelCase_)
+- Files: PascalCase.hpp / PascalCase.cpp
+- Pointer: Right-aligned (`int *ptr`)
+- Comments: Explain "why", not "what"
+- Format: clang-format (source of truth)
+
+### Detailed Conventions
+
+For complete details, see:
+
+- [Team-wide Coding Conventions](../coding-conventions/team-wide.md)
+- [C++ Coding Standards](../coding-conventions/cpp.md)
+- [Frontend Coding Standards](../coding-conventions/frontend.md)
+- [Git Commit Convention](./git-commit.md)
+
+## Technology Stack Reference
+
+### Frontend Stack
+
+- **Framework**: React 18.2+ with TypeScript 5.0+
+- **Build Tool**: Vite 4.4+
+- **State**: Redux 或 Local State（Zustand 僅既有保留）
+- **Styling**: TailwindCSS（專案已不再使用 Emotion）
+- **API Client**: Axios (standard), XMLHttpRequest (native commands only)
+- **Testing**: Vitest + React Testing Library
+
+### C++ Native Stack
+
+- **Standard**: C++17/20
+- **Memory**: Smart pointers (std::unique_ptr, std::shared_ptr)
+- **Build**: CMake
+- **Testing**: Catch2 or Google Test
+
+## Continuous Improvement
+
+- Regularly review and update these guidelines
+- Share best practices from reviews in team meetings
+- Use metrics to identify bottlenecks in the review process
+- Provide training for new team members on effective code reviews
+- Collect feedback on the review process and iterate
+
+## Related Resources
+
+- [Git Commit Convention](./git-commit.md) - Commit message format
+- [JIRA Process](./jira-process.md) - Ticket workflow
+- [Team-wide Coding Conventions](../coding-conventions/team-wide.md) - Universal standards
+- [C++ Coding Standards](../coding-conventions/cpp.md) - C++ specific rules
+- [Frontend Coding Standards](../coding-conventions/frontend.md) - React/TypeScript standards
+- [Knowledge Base](../../knowledge/) - Architectural patterns and decisions