已合并
【PR】: [feat] add precommit guide. #1298
邢智雄创建于 7月15日
【PR】: [feat] add precommit guide. #1298
已合并
共 2 个文件变更+1200-0
| @@ -0,0 +1,600 @@ | |||
| 1 | +# pre-commit Usage Guide | ||
| 2 | + | ||
| 3 | +[TOC] | ||
| 4 | +-- | ||
| 5 | + | ||
| 6 | +## 1 Background | ||
| 7 | + | ||
| 8 | +This guide is mainly for guiding how to use the pre-commit capabilities deployed in the code repository locally (mainly including code formatting and OAT scanning capabilities). | ||
| 9 | + | ||
| 10 | +## 2 Feature Overview | ||
| 11 | + | ||
| 12 | +1. After installing pre-commit, code formatting processing and OAT checks will be automatically performed before git commits. | ||
| 13 | + | ||
| 14 | +2. Compliance issues will block commits and prompt for modifications. Blocking is not forced - you can ignore the modifications. | ||
 | |||
| 15 | + | ||
| 16 | +## 3 Community Contributors Using pre-commit Capabilities | ||
| 17 | + | ||
| 18 | +### 3.1 pre-commit Installation Steps | ||
| 19 | + | ||
| 20 | +Step 1: Install pre-commit framework | ||
| 21 | + | ||
| 22 | +```bash | ||
| 23 | +# Using pip (recommended) | ||
| 24 | +pip install pre-commit | ||
| 25 | + | ||
| 26 | +# Verify installation | ||
| 27 | +pre-commit --version | ||
| 28 | +# Output: pre-commit 3.x.x | ||
| 29 | +``` | ||
| 30 | + | ||
| 31 | +**Windows Users**: Make sure Python and pip are installed. | ||
| 32 | + | ||
| 33 | +Step 2: Enter project directory | ||
| 34 | + | ||
| 35 | +```bash | ||
| 36 | +cd /path/to/your/project | ||
| 37 | + | ||
| 38 | +# For example | ||
| 39 | +cd d:\complianceRepo\CANN | ||
| 40 | +``` | ||
| 41 | + | ||
| 42 | +Step 3: Install Git Hooks | ||
| 43 | + | ||
| 44 | +```bash | ||
| 45 | +# Run in project root directory | ||
| 46 | +pre-commit install | ||
| 47 | +``` | ||
| 48 | + | ||
| 49 | +Step 4: Verify installation (optional) | ||
| 50 | + | ||
| 51 | +```bash | ||
| 52 | +# Test hook (won't actually commit) | ||
| 53 | +git commit --allow-empty -m "test pre-commit" | ||
| 54 | +``` | ||
| 55 | + | ||
| 56 | +Subsequently, code formatting processing and OAT checks will be automatically performed before committing code. | ||
| 57 | + | ||
| 58 | +### 3.2 OAT Usage Guide | ||
| 59 | + | ||
| 60 | +**OAT (Open Source Audit Tool)** is an open source compliance checking tool, automatically integrated into the Git commit workflow. | ||
| 61 | + | ||
| 62 | +#### 3.2.1 Check Content | ||
| 63 | + | ||
| 64 | +**File Type Check** - Binary files (.so, .dll, .exe, etc.) are prohibited from being submitted | ||
| 65 | +**License Header Check** - Verifies source code files contain compliant license declarations | ||
| 66 | + | ||
| 67 | +#### 3.2.2 Core Features | ||
| 68 | + | ||
| 69 | +- **Incremental Check** - Only checks files to be committed, fast (< 5 seconds) | ||
| 70 | +- **Automatic Trigger** - Runs automatically on every `git commit` | ||
| 71 | +- **Detailed Reports** - Automatically generates `result.txt` summary and full report | ||
| 72 | +- **Zero Configuration** - Java and Maven are automatically installed (Linux/macOS) | ||
| 73 | +- **Cross-Platform** - Full support for Windows/Linux/macOS | ||
| 74 | + | ||
| 75 | +#### 3.2.3 Required Software | ||
| 76 | + | ||
| 77 | +| Software | Version Requirement | Purpose | Installation Method | | ||
| 78 | +|------|---------|------|----------| | ||
| 79 | +| **Java** | JRE 8+ | Run OAT | **Auto-install** (Linux/macOS)<br> Manual install (Windows)| | ||
| 80 | +| **Maven** | 3.5+ | Package OAT | **Auto-install** (Linux/macOS)<br> Manual install (Windows)| | ||
| 81 | +| **Git** | 2.0+ | Version Control | Usually already installed | | ||
| 82 | +| **pre-commit** | 2.0+ | Hook Framework | `pip install pre-commit` | | ||
| 83 | + | ||
| 84 | +#### 3.2.4 Auto-Installation Support | ||
| 85 | + | ||
| 86 | +| Platform | Java | Maven | Package Manager | First Install Time | | ||
| 87 | +|------|------|-------|---------|-------------| | ||
| 88 | +| **Linux (Ubuntu/Debian)** | Auto | Auto | apt | 5-8 minutes | | ||
| 89 | +| **Linux (CentOS/RHEL)** | Auto | Auto | yum | 5-8 minutes | | ||
| 90 | +| **macOS** | Auto | Auto | Homebrew | 8-10 minutes | | ||
| 91 | +| **Windows** | Manual | Manual | - | Requires manual install | | ||
| 92 | + | ||
| 93 | +#### 3.2.5 Important Note: Auto-Skip on Environment Issues | ||
| 94 | + | ||
| 95 | +**Friendly Design**: If Java/Maven cannot be installed or environment issues are encountered, OAT check will **automatically skip**, and commit will continue. | ||
| 96 | + | ||
| 97 | +**Scenarios That Will Auto-Skip** | ||
| 98 | + | ||
| 99 | +| Scenario | Behavior | Prompt | | ||
| 100 | +|------|------|------| | ||
| 101 | +| Java/Maven not installed (Windows) | Skip check, allow commit | Provides manual installation guide | | ||
| 102 | +| Java/Maven auto-install fails | Skip check, allow commit | Prompts manual installation method | | ||
| 103 | +| Maven packaging fails | Skip check, allow commit | Provides solution | | ||
| 104 | +| OAT scan execution fails | Skip check, allow commit | Prompts to repackage | | ||
| 105 | + | ||
| 106 | +**Scenarios That Will Still Block Commits** | ||
| 107 | + | ||
| 108 | +| Scenario | Behavior | Reason | | ||
| 109 | +|------|------|------| | ||
| 110 | +| **Binary files found** | Block commit | Real compliance issue | | ||
| 111 | +| **License header missing/incorrect** | Block commit | Real compliance issue | | ||
| 112 | + | ||
| 113 | +**Skip Check Prompt Example** | ||
| 114 | + | ||
| 115 | +``` | ||
| 116 | +[OAT] Windows cannot auto-install Java | ||
| 117 | +[OAT] Please manually download and install: | ||
| 118 | + ... (installation steps) ... | ||
| 119 | + | ||
| 120 | +[OAT] Skipping OAT check, continuing commit... | ||
| 121 | +[OAT] Recommend installing Java and running check again | ||
| 122 | +``` | ||
| 123 | + | ||
| 124 | +**Manually Run Check Later** | ||
| 125 | + | ||
| 126 | +After configuring the environment, you can manually run the check: | ||
| 127 | + | ||
| 128 | +```bash | ||
| 129 | +# Recommended method | ||
| 130 | +pre-commit run oat-check | ||
| 131 | + | ||
| 132 | +# Or run script directly | ||
| 133 | +bash scripts/oat_check.sh | ||
| 134 | +``` | ||
| 135 | + | ||
| 136 | +#### 3.2.6 Compliance Issues (Block Commit) | ||
| 137 | + | ||
| 138 | +**Important**: The following issues will **block commits** and must be fixed. | ||
| 139 | + | ||
| 140 | +**1) Invalid File Type Found** | ||
| 141 | + | ||
| 142 | +**Scenario**: Attempting to commit binary files (.so, .dll, .exe, etc.). | ||
| 143 | + | ||
| 144 | +**Output**: | ||
| 145 | +``` | ||
| 146 | +==================================================================== | ||
| 147 | + Compliance Issues Found | ||
| 148 | +==================================================================== | ||
| 149 | + | ||
| 150 | +[OAT] Found 1 compliance issue(s): | ||
| 151 | + - Invalid File Type: 1 | ||
| 152 | + - License Header Invalid: 0 | ||
| 153 | + | ||
| 154 | +[OAT] Details saved to: oat_reports/single/result.txt | ||
| 155 | +[OAT] Please check the report and fix the issues. | ||
| 156 | + | ||
| 157 | +To view the summary: | ||
| 158 | + cat oat_reports/single/result.txt | ||
| 159 | + | ||
| 160 | +To skip this check temporarily: | ||
| 161 | + git commit --no-verify | ||
| 162 | +``` | ||
| 163 | + | ||
| 164 | +**Behavior:** **Blocks commit, must fix** | ||
| 165 | + | ||
| 166 | +**View Details**: | ||
| 167 | +```bash | ||
| 168 | +cat oat_reports/single/result.txt | ||
| 169 | +``` | ||
| 170 | + | ||
| 171 | +**Report Content Example**: | ||
| 172 | +``` | ||
| 173 | +=================================== | ||
| 174 | +OAT Scan Result Summary | ||
| 175 | +=================================== | ||
| 176 | +Scan Time: 2026-03-25 14:30:15 | ||
| 177 | +Project: CANN | ||
| 178 | +Files Checked: 1 | ||
| 179 | + | ||
| 180 | +----------------------------------- | ||
| 181 | +Invalid File Type Total Count: 1 | ||
| 182 | +lib/libtest.so: BINARY_FILE_TYPE | ||
| 183 | + | ||
| 184 | +----------------------------------- | ||
| 185 | +License Header Invalid Total Count: 0 | ||
| 186 | + | ||
| 187 | +=================================== | ||
| 188 | +Full report: oat_reports/single/PlainReport_CANN.txt | ||
| 189 | +=================================== | ||
| 190 | +``` | ||
| 191 | + | ||
| 192 | +**Solution**: | ||
| 193 | +```bash | ||
| 194 | +# Method 1: Remove binary file | ||
| 195 | +git reset HEAD lib/libtest.so | ||
| 196 | + | ||
| 197 | +# Method 2: Add binary files to .gitignore | ||
| 198 | +echo "*.so" >> .gitignore | ||
| 199 | +echo "*.dll" >> .gitignore | ||
| 200 | +echo "*.exe" >> .gitignore | ||
| 201 | + | ||
| 202 | +# Re-commit | ||
| 203 | +git add .gitignore | ||
| 204 | +git commit -m "update: add binary files to gitignore" | ||
| 205 | +``` | ||
| 206 | + | ||
| 207 | +**2) Invalid License Header** | ||
| 208 | + | ||
| 209 | +**Scenario**: Source code file is missing or has incorrect license header format. | ||
| 210 | + | ||
| 211 | +**Output**: | ||
| 212 | +``` | ||
| 213 | +==================================================================== | ||
| 214 | + Compliance Issues Found | ||
| 215 | +==================================================================== | ||
| 216 | + | ||
| 217 | +[OAT] Found 2 compliance issue(s): | ||
| 218 | + - Invalid File Type: 0 | ||
| 219 | + - License Header Invalid: 2 | ||
| 220 | + | ||
| 221 | +[OAT] Details saved to: oat_reports/single/result.txt | ||
| 222 | +``` | ||
| 223 | + | ||
| 224 | +**Behavior**: **Blocks commit, must fix** | ||
| 225 | + | ||
| 226 | +**View Details**: | ||
| 227 | +```bash | ||
| 228 | +cat oat_reports/single/result.txt | ||
| 229 | +``` | ||
| 230 | + | ||
| 231 | +**Report Content Example**: | ||
| 232 | +``` | ||
| 233 | +=================================== | ||
| 234 | +OAT Scan Result Summary | ||
| 235 | +=================================== | ||
| 236 | + | ||
| 237 | +----------------------------------- | ||
| 238 | +Invalid File Type Total Count: 0 | ||
| 239 | + | ||
| 240 | +----------------------------------- | ||
| 241 | +License Header Invalid Total Count: 2 | ||
| 242 | +src/main.cpp: MISSING_LICENSE_HEADER | ||
| 243 | +src/utils.cpp: MISSING_LICENSE_HEADER | ||
| 244 | + | ||
| 245 | +=================================== | ||
| 246 | +``` | ||
| 247 | + | ||
| 248 | +**Solution**: | ||
| 249 | + | ||
| 250 | +Add license header at the top of the file, for example CANN-2.0: | ||
| 251 | + | ||
| 252 | +```cpp | ||
| 253 | +/** | ||
| 254 | + * This program is free software, you can redistribute it and/or modify it under the terms and conditions of | ||
| 255 | + * CANN Open Software License Agreement Version 2.0 (the "License"). | ||
| 256 | + * Please refer to the License for details. You may not use this file except in compliance with the License. | ||
| 257 | + * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, | ||
| 258 | + * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. | ||
| 259 | + * See LICENSE in the root of the software repository for the full text of the License. | ||
| 260 | + */ | ||
| 261 | + | ||
| 262 | +``` | ||
| 263 | + | ||
| 264 | +**Re-commit**: | ||
| 265 | +```bash | ||
| 266 | +git add src/main.cpp src/utils.cpp | ||
| 267 | +git commit -m "fix: add license headers" | ||
| 268 | +``` | ||
| 269 | + | ||
| 270 | +--- | ||
| 271 | + | ||
| 272 | +#### 3.2.7 Report Viewing | ||
| 273 | + | ||
| 274 | +**Report File Locations** | ||
| 275 | + | ||
| 276 | +| Report Type | File Path | Content | | ||
| 277 | +|---------|---------|------| | ||
| 278 | +| **Summary Report** | `oat_reports/single/result.txt` | Key issue summary | | ||
| 279 | + | ||
| 280 | +**View Commands** | ||
| 281 | + | ||
| 282 | +```bash | ||
| 283 | +# View report | ||
| 284 | +cat oat_reports/single/result.txt | ||
| 285 | + | ||
| 286 | +# View with editor | ||
| 287 | +code oat_reports/single/result.txt | ||
| 288 | +vim oat_reports/single/result.txt | ||
| 289 | +``` | ||
| 290 | + | ||
| 291 | +**Summary Report Content** | ||
| 292 | + | ||
| 293 | +``` | ||
| 294 | +=================================== | ||
| 295 | +OAT Scan Result Summary | ||
| 296 | +=================================== | ||
| 297 | +Scan Time: 2026-03-25 14:30:15 | ||
| 298 | +Project: CANN | ||
| 299 | +Files Checked: 3 | ||
| 300 | + | ||
| 301 | +----------------------------------- | ||
| 302 | +Invalid File Type Total Count: 0 | ||
| 303 | + | ||
| 304 | +----------------------------------- | ||
| 305 | +License Header Invalid Total Count: 0 | ||
| 306 | + | ||
| 307 | +=================================== | ||
| 308 | +Full report: oat_reports/single/PlainReport_CANN.txt | ||
| 309 | +=================================== | ||
| 310 | +``` | ||
| 311 | + | ||
| 312 | +#### 3.2.8 Environment Issues | ||
| 313 | + | ||
| 314 | +**1) Java Not Installed (Linux/macOS Auto-Install)** | ||
| 315 | + | ||
| 316 | +**Scenario**: First commit, Java not installed on system. | ||
| 317 | + | ||
| 318 | +**Output**: | ||
| 319 | +``` | ||
| 320 | +==================================================================== | ||
| 321 | + Java Not Installed - Attempting Auto-Install | ||
| 322 | +==================================================================== | ||
| 323 | + | ||
| 324 | +[OAT] Detected Java not installed, starting auto-install... | ||
| 325 | +[OAT] Installing OpenJDK 11 using apt... | ||
| 326 | +[OAT] [OK] OpenJDK 11 installed successfully | ||
| 327 | +``` | ||
| 328 | + | ||
| 329 | +**Handling**: Auto-install, may require sudo password. | ||
| 330 | + | ||
| 331 | +--- | ||
| 332 | + | ||
| 333 | +**2) Java Not Installed (Windows Manual Install)** | ||
| 334 | + | ||
| 335 | +**Scenario**: Windows system cannot auto-install Java. | ||
| 336 | + | ||
| 337 | +**Output**: | ||
| 338 | +``` | ||
| 339 | +[OAT] Windows cannot auto-install Java | ||
| 340 | +[OAT] Please manually download and install: | ||
| 341 | + | ||
| 342 | + 1. Visit: https://adoptium.net/ | ||
| 343 | + 2. Download: Eclipse Temurin JRE 11 (x64) | ||
| 344 | + 3. Restart Git Bash after installation | ||
| 345 | + 4. Verify: java -version | ||
| 346 | + | ||
| 347 | +[OAT] Skipping OAT check, continuing commit... | ||
| 348 | +[OAT] Recommend installing Java and running check again | ||
| 349 | +``` | ||
| 350 | + | ||
| 351 | +**Behavior**: **Skip check, allow commit** | ||
| 352 | + | ||
| 353 | +**Follow-up Actions**: | ||
| 354 | +1. Install Java manually as prompted | ||
| 355 | +2. Restart terminal | ||
| 356 | +3. Run `pre-commit run oat-check` to verify environment | ||
| 357 | + | ||
| 358 | +--- | ||
| 359 | + | ||
| 360 | +**3) Java Auto-Install Fails** | ||
| 361 | + | ||
| 362 | +**Scenario**: Java auto-install fails on Linux/macOS. | ||
| 363 | + | ||
| 364 | +**Output**: | ||
| 365 | +``` | ||
| 366 | +[OAT] [ERROR] Auto-install failed | ||
| 367 | + | ||
| 368 | +[OAT] Auto-install failed, skipping OAT check | ||
| 369 | + | ||
| 370 | +Manual installation method: | ||
| 371 | + Linux: sudo apt install openjdk-11-jre | ||
| 372 | + macOS: brew install openjdk@11 | ||
| 373 | + Windows: https://adoptium.net/ | ||
| 374 | + | ||
| 375 | +[OAT] Continuing commit (compliance check not performed)... | ||
| 376 | +[OAT] Recommend installing Java and running: pre-commit run oat-check | ||
| 377 | +``` | ||
| 378 | + | ||
| 379 | +**Behavior**: **Skip check, allow commit** | ||
| 380 | + | ||
| 381 | +**Possible Reasons**: | ||
| 382 | +- Network connection issues | ||
| 383 | +- Package manager not configured | ||
| 384 | +- Insufficient permissions | ||
| 385 | +- Homebrew not installed on macOS | ||
| 386 | + | ||
| 387 | +**Solution**: | ||
| 388 | +```bash | ||
| 389 | +# Linux | ||
| 390 | +sudo apt update | ||
| 391 | +sudo apt install openjdk-11-jre | ||
| 392 | + | ||
| 393 | +# macOS - Install Homebrew first | ||
| 394 | +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" | ||
| 395 | +brew install openjdk@11 | ||
| 396 | + | ||
| 397 | +# Verify | ||
| 398 | +java -version | ||
| 399 | + | ||
| 400 | +# Manually run check | ||
| 401 | +pre-commit run oat-check | ||
| 402 | +``` | ||
| 403 | + | ||
| 404 | +--- | ||
| 405 | + | ||
| 406 | +**4) Maven Not Installed (Linux/macOS Auto-Install)** | ||
| 407 | + | ||
| 408 | +**Scenario**: First commit, Maven not installed on system. | ||
| 409 | + | ||
| 410 | +**Output**: | ||
| 411 | +``` | ||
| 412 | +==================================================================== | ||
| 413 | + Maven Not Installed - Attempting Auto-Install | ||
| 414 | +==================================================================== | ||
| 415 | + | ||
| 416 | +[OAT] Installing Maven using apt... | ||
| 417 | +[OAT] [OK] Maven installed successfully | ||
| 418 | +``` | ||
| 419 | + | ||
| 420 | +**Handling**: Auto-install, may require sudo password. | ||
| 421 | + | ||
| 422 | +--- | ||
| 423 | + | ||
| 424 | +**5) Maven Not Installed (Windows Manual Install)** | ||
| 425 | + | ||
| 426 | +**Scenario**: Windows system cannot auto-install Maven. | ||
| 427 | + | ||
| 428 | +**Output**: | ||
| 429 | +``` | ||
| 430 | +[OAT] Windows cannot auto-install Maven | ||
| 431 | +[OAT] Please manually download and install: | ||
| 432 | + | ||
| 433 | + 1. Visit: https://maven.apache.org/download.cgi | ||
| 434 | + 2. Download: apache-maven-3.x.x-bin.zip | ||
| 435 | + 3. Extract to C:\Program Files\apache-maven-3.x.x | ||
| 436 | + 4. Add to system PATH | ||
| 437 | + 5. Restart Git Bash | ||
| 438 | + 6. Verify: mvn -version | ||
| 439 | + | ||
| 440 | +[OAT] Skipping OAT check, continuing commit... | ||
| 441 | +[OAT] Recommend installing Maven and running check again | ||
| 442 | +``` | ||
| 443 | + | ||
| 444 | +**Behavior**: **Skip check, allow commit** | ||
| 445 | + | ||
| 446 | +**Follow-up Actions**: Install Maven manually as prompted, then run `pre-commit run oat-check` | ||
| 447 | + | ||
| 448 | +--- | ||
| 449 | + | ||
| 450 | +**6) Maven Packaging Fails** | ||
| 451 | + | ||
| 452 | +**Scenario**: Maven fails to package OAT JAR. | ||
| 453 | + | ||
| 454 | +**Output**: | ||
| 455 | +``` | ||
| 456 | +==================================================================== | ||
| 457 | + Maven Packaging Failed | ||
| 458 | +==================================================================== | ||
| 459 | + | ||
| 460 | +[OAT] Cannot package OAT JAR, skipping OAT check | ||
| 461 | + | ||
| 462 | +Possible reasons: | ||
| 463 | + 1. Maven configuration issues | ||
| 464 | + 2. Network connection issues (cannot download dependencies) | ||
| 465 | + 3. pom.xml configuration errors | ||
| 466 | + | ||
| 467 | +Suggested solutions: | ||
| 468 | + 1. Manual packaging: | ||
| 469 | + cd ../tools_oat | ||
| 470 | + mvn clean package -DskipTests | ||
| 471 | + | ||
| 472 | + 2. Configure Maven mirror (China network): | ||
| 473 | + Edit ~/.m2/settings.xml to add Aliyun mirror | ||
| 474 | + | ||
| 475 | +[OAT] Continuing commit (compliance check not performed)... | ||
| 476 | +[OAT] Recommend fixing packaging issues and running: pre-commit run oat-check | ||
| 477 | +``` | ||
| 478 | + | ||
| 479 | +**Behavior**: **Skip check, allow commit** | ||
| 480 | + | ||
| 481 | +**Solution**: | ||
| 482 | + | ||
| 483 | +**Method 1: Manual Packaging** | ||
| 484 | +```bash | ||
| 485 | +cd ../tools_oat | ||
| 486 | +mvn clean package -DskipTests | ||
| 487 | + | ||
| 488 | +# View output, should see BUILD SUCCESS | ||
| 489 | +``` | ||
| 490 | + | ||
| 491 | +**Method 2: Configure Aliyun Mirror (China Network)** | ||
| 492 | +```bash | ||
| 493 | +mkdir -p ~/.m2 | ||
| 494 | +cat > ~/.m2/settings.xml <<'EOF' | ||
| 495 | +<settings> | ||
| 496 | + <mirrors> | ||
| 497 | + <mirror> | ||
| 498 | + <id>aliyun</id> | ||
| 499 | + <mirrorOf>central</mirrorOf> | ||
| 500 | + <name>Aliyun Maven Mirror</name> | ||
| 501 | + <url>https://maven.aliyun.com/repository/public</url> | ||
| 502 | + </mirror> | ||
| 503 | + </mirrors> | ||
| 504 | +</settings> | ||
| 505 | +EOF | ||
| 506 | + | ||
| 507 | +# Re-package | ||
| 508 | +cd ../tools_oat | ||
| 509 | +mvn clean package -DskipTests | ||
| 510 | +``` | ||
| 511 | + | ||
| 512 | +**Method 3: Get JAR from Team** | ||
| 513 | +```bash | ||
| 514 | +# If team already has compiled JAR, copy directly | ||
| 515 | +# Copy JAR file to ../tools_oat/target/ directory | ||
| 516 | +``` | ||
| 517 | + | ||
| 518 | +**Verify Fix**: | ||
| 519 | +```bash | ||
| 520 | +pre-commit run oat-check | ||
| 521 | +``` | ||
| 522 | + | ||
| 523 | +--- | ||
| 524 | + | ||
| 525 | +**7) tools_oat Clone Fails** | ||
| 526 | + | ||
| 527 | +**Output**: | ||
| 528 | +``` | ||
| 529 | +[OAT] tools_oat not found. Cloning... | ||
| 530 | +[OAT] [ERROR] Failed to clone tools_oat. | ||
| 531 | +[OAT] You can manually clone from: https://gitcode.com/openharmony-sig/tools_oat.git | ||
| 532 | +``` | ||
| 533 | + | ||
| 534 | +**Reason**: Network connection issues. | ||
| 535 | + | ||
| 536 | +**Solution**: | ||
| 537 | +```bash | ||
| 538 | +# Method 1: Check network | ||
| 539 | +ping gitcode.com | ||
| 540 | + | ||
| 541 | +# Method 2: Manual clone | ||
| 542 | +cd .. | ||
| 543 | +git clone https://gitcode.com/openharmony-sig/tools_oat.git | ||
| 544 | + | ||
| 545 | +# Method 3: Configure proxy | ||
| 546 | +git config --global http.proxy http://proxy.example.com:8080 | ||
| 547 | + | ||
| 548 | +# Method 4: Copy from team member | ||
| 549 | +# Have a colleague who already cloned package the tools_oat folder for you | ||
| 550 | +``` | ||
| 551 | + | ||
| 552 | +--- | ||
| 553 | + | ||
| 554 | +**8) OAT Scan Execution Fails** | ||
| 555 | + | ||
| 556 | +**Scenario**: OAT JAR fails to run. | ||
| 557 | + | ||
| 558 | +**Output**: | ||
| 559 | +``` | ||
| 560 | +==================================================================== | ||
| 561 | + OAT Scan Execution Failed | ||
| 562 | +==================================================================== | ||
| 563 | + | ||
| 564 | +[OAT] Scan failed, skipping OAT check | ||
| 565 | + | ||
| 566 | +Possible reasons: | ||
| 567 | + 1. JAR file corrupted | ||
| 568 | + 2. Java version incompatible | ||
| 569 | + 3. OAT configuration issues | ||
| 570 | + | ||
| 571 | +Suggested solutions: | ||
| 572 | + 1. Delete and re-package JAR: | ||
| 573 | + rm ../tools_oat/target/ohos_ossaudittool-*.jar | ||
| 574 | + cd ../tools_oat && mvn clean package -DskipTests | ||
| 575 | + | ||
| 576 | + 2. Check Java version (requires Java 8+): | ||
| 577 | + java -version | ||
| 578 | + | ||
| 579 | +[OAT] Continuing commit (compliance check not performed)... | ||
| 580 | +[OAT] Recommend fixing scan issues and running: pre-commit run oat-check | ||
| 581 | +``` | ||
| 582 | + | ||
| 583 | +**Behavior**: **Skip check, allow commit** | ||
| 584 | + | ||
| 585 | +**Solution**: | ||
| 586 | +```bash | ||
| 587 | +# Step 1: Delete old JAR | ||
| 588 | +rm ../tools_oat/target/ohos_ossaudittool-*.jar | ||
| 589 | + | ||
| 590 | +# Step 2: Re-package | ||
| 591 | +cd ../tools_oat | ||
| 592 | +mvn clean package -DskipTests | ||
| 593 | + | ||
| 594 | +# Step 3: Verify JAR | ||
| 595 | +ls -lh target/ohos_ossaudittool-*.jar | ||
| 596 | + | ||
| 597 | +# Step 4: Run check | ||
| 598 | +cd - | ||
| 599 | +pre-commit run oat-check | ||
| 600 | +``` | ||
| @@ -0,0 +1,600 @@ | |||
| 1 | +# pre-commit使用指导书 | ||
| 2 | + | ||
| 3 | +[TOC] | ||
| 4 | +-- | ||
| 5 | + | ||
| 6 | +## 1 使用背景 | ||
| 7 | + | ||
| 8 | +本指导书主要用于指导如何在本地使用代码仓中部署的pre-commit能力（主要包括代码格式化及OAT扫描能力）。 | ||
| 9 | + | ||
| 10 | +## 2 功能概述 | ||
| 11 | + | ||
| 12 | +1、安装pre-commit后，git提交代码前会自动进行代码格式化处理及触发OAT检查。 | ||
| 13 | + | ||
| 14 | +2、合规性问题会阻止提交并提示修改，阻止并非强制修改，可以忽略修改。 | ||
🟠 High Priority 中文版第 14 行明确声明 "阻止并非强制修改，可以忽略修改"，且第 160-161 行在合规问题章节中直接将
changed line → affected behavior: 第 14 行和第 160-161 行 → 用户获知可无条件绕过 pre-commit 检查 → 不合规代码可能被提交。 建议：删除或修改第 14 行的"可以忽略修改"表述，并将第 160-161 行的   | |||
| 15 | + | ||
| 16 | +## 3 社区贡献者使用pre-commit能力 | ||
| 17 | + | ||
| 18 | +### 3.1 pre-commit安装步骤 | ||
| 19 | + | ||
| 20 | +步骤 1: 安装 pre-commit 框架 | ||
| 21 | + | ||
| 22 | +```bash | ||
| 23 | +# 使用 pip（推荐） | ||
| 24 | +pip install pre-commit | ||
| 25 | + | ||
| 26 | +# 验证安装 | ||
| 27 | +pre-commit --version | ||
| 28 | +# 输出: pre-commit 3.x.x | ||
| 29 | +``` | ||
| 30 | + | ||
| 31 | +**Windows 用户**: 确保已安装 Python 和 pip。 | ||
| 32 | + | ||
| 33 | +步骤 2: 进入项目目录 | ||
| 34 | + | ||
| 35 | +```bash | ||
| 36 | +cd /path/to/your/project | ||
| 37 | + | ||
| 38 | +# 例如 | ||
| 39 | +cd d:\complianceRepo\CANN | ||
| 40 | +``` | ||
| 41 | + | ||
| 42 | +步骤 3: 安装 Git Hooks | ||
| 43 | + | ||
| 44 | +```bash | ||
| 45 | +# 在项目根目录运行 | ||
| 46 | +pre-commit install | ||
| 47 | +``` | ||
| 48 | + | ||
| 49 | +步骤 4: 验证安装（可选） | ||
| 50 | + | ||
| 51 | +```bash | ||
| 52 | +# 测试 hook（不会真正提交） | ||
| 53 | +git commit --allow-empty -m "test pre-commit" | ||
| 54 | +``` | ||
| 55 | + | ||
| 56 | +后续在提交代码前会自动进行代码格式化处理及触发OAT检查。 | ||
| 57 | + | ||
| 58 | +### 3.2 OAT使用指导 | ||
| 59 | + | ||
| 60 | +**OAT（Open Source Audit Tool）** 是一个开源合规性检查工具，自动集成到 Git 提交流程中。 | ||
| 61 | + | ||
| 62 | +#### 3.2.1 检查内容 | ||
| 63 | + | ||
| 64 | +**文件类型检查** - 禁止提交二进制文件（.so, .dll, .exe 等） | ||
| 65 | +**许可证头检查** - 验证源代码文件包含合规的许可证声明 | ||
| 66 | + | ||
| 67 | +#### 3.2.2 核心特点 | ||
| 68 | + | ||
| 69 | +- **增量检查** - 仅检查待提交文件，速度快（< 5 秒） | ||
| 70 | +- **自动触发** - 每次 `git commit` 自动运行 | ||
| 71 | +- **详细报告** - 自动生成 `result.txt` 摘要和完整报告 | ||
| 72 | +- **零配置** - Java 和 Maven 自动安装（Linux/macOS） | ||
| 73 | +- **跨平台** - Windows/Linux/macOS 全支持 | ||
| 74 | + | ||
| 75 | +#### 3.2.3 必需软件 | ||
| 76 | + | ||
| 77 | +| 软件 | 版本要求 | 用途 | 安装方式 | | ||
| 78 | +|------|---------|------|----------| | ||
| 79 | +| **Java** | JRE 8+ | 运行 OAT | **自动安装**（Linux/macOS）<br> 手动安装（Windows）| | ||
| 80 | +| **Maven** | 3.5+ | 打包 OAT | **自动安装**（Linux/macOS）<br> 手动安装（Windows）| | ||
| 81 | +| **Git** | 2.0+ | 版本控制 | 通常已安装 | | ||
| 82 | +| **pre-commit** | 2.0+ | Hook 框架 | `pip install pre-commit` | | ||
| 83 | + | ||
| 84 | +#### 3.2.4 自动安装支持 | ||
| 85 | + | ||
| 86 | +| 平台 | Java | Maven | 包管理器 | 首次安装时间 | | ||
| 87 | +|------|------|-------|---------|-------------| | ||
| 88 | +| **Linux (Ubuntu/Debian)** | 自动 | 自动 | apt | 5-8 分钟 | | ||
| 89 | +| **Linux (CentOS/RHEL)** | 自动 | 自动 | yum | 5-8 分钟 | | ||
| 90 | +| **macOS** | 自动 | 自动 | Homebrew | 8-10 分钟 | | ||
| 91 | +| **Windows** | 手动 | 手动 | - | 需手动安装 | | ||
| 92 | + | ||
| 93 | +#### 3.2.5 重要提示：环境问题自动跳过 | ||
| 94 | + | ||
| 95 | +**友好的设计**：如果无法安装 Java/Maven 或遇到环境问题，OAT 检查会**自动跳过**，提交仍会继续。 | ||
| 96 | + | ||
| 97 | +**会自动跳过的场景** | ||
| 98 | + | ||
| 99 | +| 场景 | 行为 | 提示 | | ||
| 100 | +|------|------|------| | ||
| 101 | +| Java/Maven 未安装（Windows） | 跳过检查，允许提交 | 提供手动安装指引 | | ||
| 102 | +| Java/Maven 自动安装失败 | 跳过检查，允许提交 | 提示手动安装方法 | | ||
| 103 | +| Maven 打包失败 | 跳过检查，允许提交 | 提供解决方案 | | ||
| 104 | +| OAT 扫描执行失败 | 跳过检查，允许提交 | 提示重新打包 | | ||
| 105 | + | ||
| 106 | +** 仍会阻止提交的场景** | ||
| 107 | + | ||
| 108 | +| 场景 | 行为 | 原因 | | ||
| 109 | +|------|------|------| | ||
| 110 | +| **发现二进制文件** | 阻止提交 | 真正的合规性问题 | | ||
| 111 | +| **许可证头缺失/错误** | 阻止提交 | 真正的合规性问题 | | ||
| 112 | + | ||
| 113 | +**跳过检查的提示示例** | ||
| 114 | + | ||
| 115 | +``` | ||
| 116 | +[OAT] Windows 系统无法自动安装 Java | ||
| 117 | +[OAT] 请手动下载并安装： | ||
| 118 | + ...（安装步骤）... | ||
| 119 | + | ||
| 120 | +[OAT] 跳过 OAT 检查，继续提交... | ||
| 121 | +[OAT] 建议安装 Java 后再次运行检查 | ||
| 122 | +``` | ||
| 123 | + | ||
| 124 | +**后续手动运行检查** | ||
| 125 | + | ||
| 126 | +配置好环境后，可以手动运行检查： | ||
| 127 | + | ||
| 128 | +```bash | ||
| 129 | +# 推荐方式 | ||
| 130 | +pre-commit run oat-check | ||
| 131 | + | ||
| 132 | +# 或直接运行脚本 | ||
| 133 | +bash scripts/oat_check.sh | ||
| 134 | +``` | ||
| 135 | + | ||
| 136 | +#### 3.2.6 合规性问题（阻止提交） | ||
| 137 | + | ||
| 138 | +**重要**: 以下问题会**阻止提交**，必须修复。 | ||
| 139 | + | ||
| 140 | +**1) 发现无效文件类型** | ||
| 141 | + | ||
| 142 | +**场景**: 尝试提交二进制文件（.so, .dll, .exe 等）。 | ||
| 143 | + | ||
| 144 | +**输出**: | ||
| 145 | +``` | ||
| 146 | +==================================================================== | ||
| 147 | + 发现合规性问题 | ||
| 148 | +==================================================================== | ||
| 149 | + | ||
| 150 | +[OAT] Found 1 compliance issue(s): | ||
| 151 | + - Invalid File Type: 1 | ||
| 152 | + - License Header Invalid: 0 | ||
| 153 | + | ||
| 154 | +[OAT] Details saved to: oat_reports/single/result.txt | ||
| 155 | +[OAT] Please check the report and fix the issues. | ||
| 156 | + | ||
| 157 | +To view the summary: | ||
| 158 | + cat oat_reports/single/result.txt | ||
| 159 | + | ||
| 160 | +To skip this check temporarily: | ||
| 161 | + git commit --no-verify | ||
| 162 | +``` | ||
| 163 | + | ||
| 164 | +**行为**:**阻止提交，必须修复** | ||
| 165 | + | ||
| 166 | +**查看详情**: | ||
| 167 | +```bash | ||
| 168 | +cat oat_reports/single/result.txt | ||
| 169 | +``` | ||
| 170 | + | ||
| 171 | +**报告内容示例**: | ||
| 172 | +``` | ||
| 173 | +=================================== | ||
| 174 | +OAT Scan Result Summary | ||
| 175 | +=================================== | ||
| 176 | +Scan Time: 2026-03-25 14:30:15 | ||
| 177 | +Project: CANN | ||
| 178 | +Files Checked: 1 | ||
| 179 | + | ||
| 180 | +----------------------------------- | ||
| 181 | +Invalid File Type Total Count: 1 | ||
| 182 | +lib/libtest.so: BINARY_FILE_TYPE | ||
| 183 | + | ||
| 184 | +----------------------------------- | ||
| 185 | +License Header Invalid Total Count: 0 | ||
| 186 | + | ||
| 187 | +=================================== | ||
| 188 | +Full report: oat_reports/single/PlainReport_CANN.txt | ||
| 189 | +=================================== | ||
| 190 | +``` | ||
| 191 | + | ||
| 192 | +**解决方案**: | ||
| 193 | +```bash | ||
| 194 | +# 方法 1: 移除二进制文件 | ||
| 195 | +git reset HEAD lib/libtest.so | ||
| 196 | + | ||
| 197 | +# 方法 2: 将二进制文件添加到 .gitignore | ||
| 198 | +echo "*.so" >> .gitignore | ||
| 199 | +echo "*.dll" >> .gitignore | ||
| 200 | +echo "*.exe" >> .gitignore | ||
| 201 | + | ||
| 202 | +# 重新提交 | ||
| 203 | +git add .gitignore | ||
| 204 | +git commit -m "update: add binary files to gitignore" | ||
| 205 | +``` | ||
| 206 | + | ||
| 207 | +**2) 许可证头无效** | ||
| 208 | + | ||
| 209 | +**场景**: 源代码文件缺少或许可证头格式不正确。 | ||
| 210 | + | ||
| 211 | +**输出**: | ||
| 212 | +``` | ||
| 213 | +==================================================================== | ||
| 214 | + 发现合规性问题 | ||
| 215 | +==================================================================== | ||
| 216 | + | ||
| 217 | +[OAT] Found 2 compliance issue(s): | ||
| 218 | + - Invalid File Type: 0 | ||
| 219 | + - License Header Invalid: 2 | ||
| 220 | + | ||
| 221 | +[OAT] Details saved to: oat_reports/single/result.txt | ||
| 222 | +``` | ||
| 223 | + | ||
| 224 | +**行为**: **阻止提交，必须修复** | ||
| 225 | + | ||
| 226 | +**查看详情**: | ||
| 227 | +```bash | ||
| 228 | +cat oat_reports/single/result.txt | ||
| 229 | +``` | ||
| 230 | + | ||
| 231 | +**报告内容示例**: | ||
| 232 | +``` | ||
| 233 | +=================================== | ||
| 234 | +OAT Scan Result Summary | ||
| 235 | +=================================== | ||
| 236 | + | ||
| 237 | +----------------------------------- | ||
| 238 | +Invalid File Type Total Count: 0 | ||
| 239 | + | ||
| 240 | +----------------------------------- | ||
| 241 | +License Header Invalid Total Count: 2 | ||
| 242 | +src/main.cpp: MISSING_LICENSE_HEADER | ||
| 243 | +src/utils.cpp: MISSING_LICENSE_HEADER | ||
| 244 | + | ||
| 245 | +=================================== | ||
| 246 | +``` | ||
| 247 | + | ||
| 248 | +**解决方案**: | ||
| 249 | + | ||
| 250 | +在文件顶部添加许可证头，例如 CANN-2.0： | ||
| 251 | + | ||
| 252 | +```cpp | ||
| 253 | +/** | ||
| 254 | + * This program is free software, you can redistribute it and/or modify it under the terms and conditions of | ||
| 255 | + * CANN Open Software License Agreement Version 2.0 (the "License"). | ||
| 256 | + * Please refer to the License for details. You may not use this file except in compliance with the License. | ||
| 257 | + * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, | ||
| 258 | + * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. | ||
| 259 | + * See LICENSE in the root of the software repository for the full text of the License. | ||
| 260 | + */ | ||
| 261 | + | ||
| 262 | +``` | ||
| 263 | + | ||
| 264 | +**重新提交**: | ||
| 265 | +```bash | ||
| 266 | +git add src/main.cpp src/utils.cpp | ||
| 267 | +git commit -m "fix: add license headers" | ||
| 268 | +``` | ||
| 269 | + | ||
| 270 | +--- | ||
| 271 | + | ||
| 272 | +#### 3.2.7 报告查看 | ||
| 273 | + | ||
| 274 | +**报告文件位置** | ||
| 275 | + | ||
| 276 | +| 报告类型 | 文件路径 | 内容 | | ||
| 277 | +|---------|---------|------| | ||
| 278 | +| **摘要报告** | `oat_reports/single/result.txt` | 关键问题汇总 | | ||
| 279 | + | ||
| 280 | +**查看命令** | ||
| 281 | + | ||
| 282 | +```bash | ||
| 283 | +# 查看报告 | ||
| 284 | +cat oat_reports/single/result.txt | ||
| 285 | + | ||
| 286 | +# 使用编辑器查看 | ||
| 287 | +code oat_reports/single/result.txt | ||
| 288 | +vim oat_reports/single/result.txt | ||
| 289 | +``` | ||
| 290 | + | ||
| 291 | +**摘要报告内容** | ||
| 292 | + | ||
| 293 | +``` | ||
| 294 | +=================================== | ||
| 295 | +OAT Scan Result Summary | ||
| 296 | +=================================== | ||
| 297 | +Scan Time: 2026-03-25 14:30:15 | ||
| 298 | +Project: CANN | ||
| 299 | +Files Checked: 3 | ||
| 300 | + | ||
| 301 | +----------------------------------- | ||
| 302 | +Invalid File Type Total Count: 0 | ||
| 303 | + | ||
| 304 | +----------------------------------- | ||
| 305 | +License Header Invalid Total Count: 0 | ||
| 306 | + | ||
| 307 | +=================================== | ||
| 308 | +Full report: oat_reports/single/PlainReport_CANN.txt | ||
| 309 | +=================================== | ||
| 310 | +``` | ||
| 311 | + | ||
| 312 | +#### 3.2.8 环境问题 | ||
| 313 | + | ||
| 314 | +**1) Java 未安装（Linux/macOS 自动安装）** | ||
| 315 | + | ||
| 316 | +**场景**: 首次提交，系统未安装 Java。 | ||
| 317 | + | ||
| 318 | +**输出**: | ||
| 319 | +``` | ||
| 320 | +==================================================================== | ||
| 321 | + Java 未安装 - 正在尝试自动安装 | ||
| 322 | +==================================================================== | ||
| 323 | + | ||
| 324 | +[OAT] 检测到系统未安装 Java，开始自动安装... | ||
| 325 | +[OAT] 使用 apt 安装 OpenJDK 11... | ||
| 326 | +[OAT] [OK] OpenJDK 11 安装成功 | ||
| 327 | +``` | ||
| 328 | + | ||
| 329 | +**处理**: 自动安装，可能需要输入 sudo 密码。 | ||
| 330 | + | ||
| 331 | +--- | ||
| 332 | + | ||
| 333 | +**2) Java 未安装（Windows 手动安装）** | ||
| 334 | + | ||
| 335 | +**场景**: Windows 系统无法自动安装 Java。 | ||
| 336 | + | ||
| 337 | +**输出**: | ||
| 338 | +``` | ||
| 339 | +[OAT] Windows 系统无法自动安装 Java | ||
| 340 | +[OAT] 请手动下载并安装： | ||
| 341 | + | ||
| 342 | + 1. 访问: https://adoptium.net/ | ||
| 343 | + 2. 下载: Eclipse Temurin JRE 11 (x64) | ||
| 344 | + 3. 安装后重启 Git Bash | ||
| 345 | + 4. 验证: java -version | ||
| 346 | + | ||
| 347 | +[OAT] 跳过 OAT 检查，继续提交... | ||
| 348 | +[OAT] 建议安装 Java 后再次运行检查 | ||
| 349 | +``` | ||
| 350 | + | ||
| 351 | +**行为**: **跳过检查，允许提交** | ||
| 352 | + | ||
| 353 | +**后续操作**: | ||
| 354 | +1. 按提示手动安装 Java | ||
| 355 | +2. 重启终端 | ||
| 356 | +3. 运行 `pre-commit run oat-check` 验证环境 | ||
| 357 | + | ||
| 358 | +--- | ||
| 359 | + | ||
| 360 | +**3) Java 自动安装失败** | ||
| 361 | + | ||
| 362 | +**场景**: Linux/macOS 自动安装 Java 失败。 | ||
| 363 | + | ||
| 364 | +**输出**: | ||
| 365 | +``` | ||
| 366 | +[OAT] [ERROR] 自动安装失败 | ||
| 367 | + | ||
| 368 | +[OAT] 自动安装失败，跳过 OAT 检查 | ||
| 369 | + | ||
| 370 | +手动安装方法: | ||
| 371 | + Linux: sudo apt install openjdk-11-jre | ||
| 372 | + macOS: brew install openjdk@11 | ||
| 373 | + Windows: https://adoptium.net/ | ||
| 374 | + | ||
| 375 | +[OAT] 继续提交（未进行合规性检查）... | ||
| 376 | +[OAT] 建议安装 Java 后再次运行: pre-commit run oat-check | ||
| 377 | +``` | ||
| 378 | + | ||
| 379 | +**行为**: **跳过检查，允许提交** | ||
| 380 | + | ||
| 381 | +**可能原因**: | ||
| 382 | +- 网络连接问题 | ||
| 383 | +- 包管理器未配置 | ||
| 384 | +- 权限不足 | ||
| 385 | +- macOS 未安装 Homebrew | ||
| 386 | + | ||
| 387 | +**解决方案**: | ||
| 388 | +```bash | ||
| 389 | +# Linux | ||
| 390 | +sudo apt update | ||
| 391 | +sudo apt install openjdk-11-jre | ||
| 392 | + | ||
| 393 | +# macOS - 先安装 Homebrew | ||
| 394 | +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" | ||
| 395 | +brew install openjdk@11 | ||
| 396 | + | ||
| 397 | +# 验证 | ||
| 398 | +java -version | ||
| 399 | + | ||
| 400 | +# 手动运行检查 | ||
| 401 | +pre-commit run oat-check | ||
| 402 | +``` | ||
| 403 | + | ||
| 404 | +--- | ||
| 405 | + | ||
| 406 | +**4) Maven 未安装（Linux/macOS 自动安装）** | ||
| 407 | + | ||
| 408 | +**场景**: 首次提交，系统未安装 Maven。 | ||
| 409 | + | ||
| 410 | +**输出**: | ||
| 411 | +``` | ||
| 412 | +==================================================================== | ||
| 413 | + Maven 未安装 - 正在尝试自动安装 | ||
| 414 | +==================================================================== | ||
| 415 | + | ||
| 416 | +[OAT] 使用 apt 安装 Maven... | ||
| 417 | +[OAT] [OK] Maven 安装成功 | ||
| 418 | +``` | ||
| 419 | + | ||
| 420 | +**处理**: 自动安装，可能需要输入 sudo 密码。 | ||
| 421 | + | ||
| 422 | +--- | ||
| 423 | + | ||
| 424 | +**5) Maven 未安装（Windows 手动安装）** | ||
| 425 | + | ||
| 426 | +**场景**: Windows 系统无法自动安装 Maven。 | ||
| 427 | + | ||
| 428 | +**输出**: | ||
| 429 | +``` | ||
| 430 | +[OAT] Windows 系统无法自动安装 Maven | ||
| 431 | +[OAT] 请手动下载并安装： | ||
| 432 | + | ||
| 433 | + 1. 访问: https://maven.apache.org/download.cgi | ||
| 434 | + 2. 下载: apache-maven-3.x.x-bin.zip | ||
| 435 | + 3. 解压到 C:\Program Files\apache-maven-3.x.x | ||
| 436 | + 4. 添加到系统 PATH | ||
| 437 | + 5. 重启 Git Bash | ||
| 438 | + 6. 验证: mvn -version | ||
| 439 | + | ||
| 440 | +[OAT] 跳过 OAT 检查，继续提交... | ||
| 441 | +[OAT] 建议安装 Maven 后再次运行检查 | ||
| 442 | +``` | ||
| 443 | + | ||
| 444 | +**行为**: **跳过检查，允许提交** | ||
| 445 | + | ||
| 446 | +**后续操作**: 按提示手动安装 Maven，然后运行 `pre-commit run oat-check` | ||
| 447 | + | ||
| 448 | +--- | ||
| 449 | + | ||
| 450 | +**6) Maven 打包失败** | ||
| 451 | + | ||
| 452 | +**场景**: Maven 打包 OAT JAR 失败。 | ||
| 453 | + | ||
| 454 | +**输出**: | ||
| 455 | +``` | ||
| 456 | +==================================================================== | ||
| 457 | + Maven 打包失败 | ||
| 458 | +==================================================================== | ||
| 459 | + | ||
| 460 | +[OAT] 无法打包 OAT JAR，跳过 OAT 检查 | ||
| 461 | + | ||
| 462 | +可能原因: | ||
| 463 | + 1. Maven 配置问题 | ||
| 464 | + 2. 网络连接问题（无法下载依赖） | ||
| 465 | + 3. pom.xml 配置错误 | ||
| 466 | + | ||
| 467 | +建议解决方案: | ||
| 468 | + 1. 手动打包： | ||
| 469 | + cd ../tools_oat | ||
| 470 | + mvn clean package -DskipTests | ||
| 471 | + | ||
| 472 | + 2. 配置 Maven 镜像（国内网络）： | ||
| 473 | + 编辑 ~/.m2/settings.xml 添加阿里云镜像 | ||
| 474 | + | ||
| 475 | +[OAT] 继续提交（未进行合规性检查）... | ||
| 476 | +[OAT] 建议修复打包问题后运行: pre-commit run oat-check | ||
| 477 | +``` | ||
| 478 | + | ||
| 479 | +**行为**: **跳过检查，允许提交** | ||
| 480 | + | ||
| 481 | +**解决方案**: | ||
| 482 | + | ||
| 483 | +**方法 1: 手动打包** | ||
| 484 | +```bash | ||
| 485 | +cd ../tools_oat | ||
| 486 | +mvn clean package -DskipTests | ||
| 487 | + | ||
| 488 | +# 查看输出，应该看到 BUILD SUCCESS | ||
| 489 | +``` | ||
| 490 | + | ||
| 491 | +**方法 2: 配置阿里云镜像（国内网络）** | ||
| 492 | +```bash | ||
| 493 | +mkdir -p ~/.m2 | ||
| 494 | +cat > ~/.m2/settings.xml <<'EOF' | ||
| 495 | +<settings> | ||
| 496 | + <mirrors> | ||
| 497 | + <mirror> | ||
| 498 | + <id>aliyun</id> | ||
| 499 | + <mirrorOf>central</mirrorOf> | ||
| 500 | + <name>Aliyun Maven Mirror</name> | ||
| 501 | + <url>https://maven.aliyun.com/repository/public</url> | ||
| 502 | + </mirror> | ||
| 503 | + </mirrors> | ||
| 504 | +</settings> | ||
| 505 | +EOF | ||
| 506 | + | ||
| 507 | +# 重新打包 | ||
| 508 | +cd ../tools_oat | ||
| 509 | +mvn clean package -DskipTests | ||
| 510 | +``` | ||
| 511 | + | ||
| 512 | +**方法 3: 从团队获取 JAR** | ||
| 513 | +```bash | ||
| 514 | +# 如果团队已有编译好的 JAR，直接复制 | ||
| 515 | +# 将 JAR 文件复制到 ../tools_oat/target/ 目录 | ||
| 516 | +``` | ||
| 517 | + | ||
| 518 | +**验证修复**: | ||
| 519 | +```bash | ||
| 520 | +pre-commit run oat-check | ||
| 521 | +``` | ||
| 522 | + | ||
| 523 | +--- | ||
| 524 | + | ||
| 525 | +**7) tools_oat 克隆失败** | ||
| 526 | + | ||
| 527 | +**输出**: | ||
| 528 | +``` | ||
| 529 | +[OAT] tools_oat not found. Cloning... | ||
| 530 | +[OAT] [ERROR] Failed to clone tools_oat. | ||
| 531 | +[OAT] You can manually clone from: https://gitcode.com/openharmony-sig/tools_oat.git | ||
| 532 | +``` | ||
| 533 | + | ||
| 534 | +**原因**: 网络连接问题。 | ||
| 535 | + | ||
| 536 | +**解决方案**: | ||
| 537 | +```bash | ||
| 538 | +# 方法 1: 检查网络 | ||
| 539 | +ping gitcode.com | ||
| 540 | + | ||
| 541 | +# 方法 2: 手动克隆 | ||
| 542 | +cd .. | ||
| 543 | +git clone https://gitcode.com/openharmony-sig/tools_oat.git | ||
| 544 | + | ||
| 545 | +# 方法 3: 配置代理 | ||
| 546 | +git config --global http.proxy http://proxy.example.com:8080 | ||
| 547 | + | ||
| 548 | +# 方法 4: 从团队成员复制 | ||
| 549 | +# 让已克隆的同事打包 tools_oat 文件夹给你 | ||
| 550 | +``` | ||
| 551 | + | ||
| 552 | +--- | ||
| 553 | + | ||
| 554 | +**8) OAT 扫描执行失败** | ||
| 555 | + | ||
| 556 | +**场景**: OAT JAR 运行失败。 | ||
| 557 | + | ||
| 558 | +**输出**: | ||
| 559 | +``` | ||
| 560 | +==================================================================== | ||
| 561 | + OAT 扫描执行失败 | ||
| 562 | +==================================================================== | ||
| 563 | + | ||
| 564 | +[OAT] 扫描失败，跳过 OAT 检查 | ||
| 565 | + | ||
| 566 | +可能原因: | ||
| 567 | + 1. JAR 文件损坏 | ||
| 568 | + 2. Java 版本不兼容 | ||
| 569 | + 3. OAT 配置问题 | ||
| 570 | + | ||
| 571 | +建议解决方案: | ||
| 572 | + 1. 删除并重新打包 JAR： | ||
| 573 | + rm ../tools_oat/target/ohos_ossaudittool-*.jar | ||
| 574 | + cd ../tools_oat && mvn clean package -DskipTests | ||
| 575 | + | ||
| 576 | + 2. 检查 Java 版本（需要 Java 8+）： | ||
| 577 | + java -version | ||
| 578 | + | ||
| 579 | +[OAT] 继续提交（未进行合规性检查）... | ||
| 580 | +[OAT] 建议修复扫描问题后运行: pre-commit run oat-check | ||
| 581 | +``` | ||
| 582 | + | ||
| 583 | +**行为**: **跳过检查，允许提交** | ||
| 584 | + | ||
| 585 | +**解决方案**: | ||
| 586 | +```bash | ||
| 587 | +# 步骤 1: 删除旧 JAR | ||
| 588 | +rm ../tools_oat/target/ohos_ossaudittool-*.jar | ||
| 589 | + | ||
| 590 | +# 步骤 2: 重新打包 | ||
| 591 | +cd ../tools_oat | ||
| 592 | +mvn clean package -DskipTests | ||
| 593 | + | ||
| 594 | +# 步骤 3: 验证 JAR | ||
| 595 | +ls -lh target/ohos_ossaudittool-*.jar | ||
| 596 | + | ||
| 597 | +# 步骤 4: 运行检查 | ||
| 598 | +cd - | ||
| 599 | +pre-commit run oat-check | ||
| 600 | +``` | ||
🟠 High Priority
英文版第 14 行明确声明 "Blocking is not forced - you can ignore the modifications."，且第 160-161 行在合规问题章节中直接将
git commit --no-verify作为"temporarily skip this check"的解决方案展示给用户。--no-verify会绕过所有 pre-commit hooks（不仅仅是 OAT），包括代码格式化等。pre-commit 机制的设计初衷是在提交前强制进行合规检查，而文档却在教导用户如何跳过，这直接削弱了合规管控的有效性。用户在了解此方法后，可能在任何合规问题（二进制文件、许可证头缺失）出现时直接绕过，导致不合规代码进入仓库。changed line → affected behavior: 第 14 行和第 160-161 行 → 用户获知可无条件绕过 pre-commit 检查 → 不合规代码可能被提交。
建议：删除或修改第 14 行的"可以忽略"表述，并将第 160-161 行的
--no-verify绕过方法移除，或至少添加明确的警告说明这是最后的应急手段，不应在日常开发中常规使用，且使用后必须随后运行pre-commit run oat-check补检。