贡献指南

感谢您参与 Global Trust Authority (GTA) 项目的贡献！我们欢迎并感谢各种形式的贡献——缺陷修复、新功能、文档改进、证明插件实现以及测试。遵循本指南有助于确保评审流程顺畅高效。

---

开始之前

1. 检索已有工作 先查看本仓库的 issue 与 merge request，确认是否已有人在处理相同想法或问题。

2. 大型变更先讨论 对于重大变更或新功能，请先开 issue 与维护者讨论设计、范围与实现方案。GTA 涉及远程证明、密钥管理、nonce 防重放与令牌签名等安全敏感路径（见 AGENTS.md § Security-Sensitive Areas 与 docs/zh/architecture.md）；凡涉及这些边界的变更，设计对齐尤为重要。

3. 阅读代理与规范指南 AGENTS.md 记录了 workspace 布局、构建命令、命名、测试组织以及每项变更必须遵守的约定。

---

如何贡献

按以下步骤准备并提交您的贡献。

1. Fork 与克隆

先将仓库 fork 到您的 GitCode 账号，并在本地克隆：

# HTTPS
git clone https://gitcode.com/<your-username>/global-trust-authority.git
# 或 SSH
git clone git@gitcode.com:<your-username>/global-trust-authority.git
cd global-trust-authority

2. 搭建项目

构建与安装说明见 docs/en/GTA_Usage_Guidelines.md。最低前置要求：

• Linux x86_64 或 aarch64（macOS/Windows 非主平台；可用 WSL2 或 Docker Compose 流程）
• Rust stable 工具链，MSRV 1.82+（若 cargo build 报 Cargo.lock 错误，请用 rustup）
• openssl、git、cmake、gcc 等基础构建工具
• 完整原生构建还需：tpm2-tss-devel、clang、libboundscheck、virtCCA_sdk、virtCCA_sdk-devel、itrustee_sdk 等（详见 AGENTS.md Build prerequisites 与 scripts/pipeline_code_check.sh）

部分 crate 可在标准 Rust 工具链下做增量校验，例如：

cargo check --package attestation

Docker 快速体验（服务 + MySQL + Redis）：

docker compose -f docker/docker-compose.yaml up

3. 创建分支

创建一个描述性强的新分支。发布分支使用 br_feat_* 前缀；日常贡献推荐使用下列前缀之一：

• feature/ 新功能。
• fix/ 缺陷修复。
• chore/ 维护或构建相关。
• doc/ 仅文档变更。
• test/ 仅测试变更。

git checkout -b feature/your-feature-name

4. 修改代码

聚焦单一关注点： 尽可能让变更只围绕一个主题。

遵守规范： 遵循 AGENTS.md 中的编码风格与约定，特别注意：

• 运行 cargo fmt——格式由 rustfmt.toml 控制（max_width = 120、Unix 换行）。
• 运行 cargo clippy -- --cap-lints warn -W clippy::all -A clippy::restriction 并清理警告。
• 每个 .rs 文件须保留项目规定的 Mulan PSL v2 版权头。
• 生产代码中不得使用 unwrap()、expect()、todo!() 或 unimplemented!()。
• 新增或修改 IO 操作时，应尽可能使用 async；避免在高频异步请求路径中执行阻塞 IO，且异步上下文中避免 std::sync::Mutex。
• 配置通过 config_manager 与 env_config_parse 加载，不得硬编码。
• 注释应谨慎添加，仅在阐明非显而易见的行为时使用；保持公开 API 文档最新——与周围代码风格保持一致。
• 语言要求： 代码注释与项目文档（docs/、AGENTS.md、.sdd/ 等）使用英文；提交信息可采用中英文混排，与现有历史一致（如 feat:、fix:、docs:）；本双语 CONTRIBUTING.md 除外。

文档化代码： 保持公开 API 有文档。REST API、CLI 或 agent 行为变更时，同步更新 §6 所列文档。

保持一致性： 确保文档、注释与代码实现保持一致——涵盖 AGENTS.md、docs/、.sdd/、测试代码、构建脚本、部署配置及相关文档。任何行为变更须同步更新所有相关产物；不得留下与代码不符的过时文档或注释。

5. 新增或更新测试

GTA 以 Rust 单元/集成测试为主，请在对应 crate 覆盖您的变更：

层级	运行器	位置
单元测试	cargo test	各 crate 内 #[cfg(test)] 模块
集成测试	cargo test	各 crate 的 tests/test_*.rs
Mock 插件	cargo test	各 crate 下的独立 mock crate（如 plugin_manager/tests/mock_plugin_for_service/、attestation_server/attestation/tests/mock_test_attester/）

优先使用公开 API 与 crate 内 #[cfg(test)] 模块。

• Service（attestation_server/）：REST handler、策略引擎、验证器变更应在对应 crate 的 tests/ 下增补或更新测试。
• Agent（attestation_agent/）：attester 或 challenge 流程变更应在对应 crate 下增补测试；涉及 TPM 等硬件时考虑 serial_test。
• CLI（attestation_cli）：命令或参数变更应增补集成测试。
• Key Manager（key_manager）：密钥与 mTLS 相关变更应增补测试；夹具数据放在 key_manager/tests/testdata/。

示例：

cargo test --package attestation
cargo test --package challenge
cargo test --package attestation test_attestation_chain

新增硬件证明类型时，须同时实现 attester 与 verifier，并通过 agent/server 插件配置加载，避免在插件系统外硬编码（见 AGENTS.md § Adding a New Attestation Type）。

6. 必要时同步文档

按变更所在组件更新文档：

REST API（attestation_server）

若新增或修改 API 端点或参数，更新：

• docs/en/api_documentation.md
• docs/zh/api_documentation.md

保持中英文 API 文档内容一致。

Service 模块（attestation_server，非 REST API）

• 服务组件、运行时流程或模块边界变更：更新 docs/en/attestation_service.md 与 docs/zh/attestation_service.md。

Common 基础设施（attestation_common）

• 缓存、数据库、消息队列等公共 crate 变更：更新 docs/en/attestation_common.md 与 docs/zh/attestation_common.md。

CLI（attestation_cli）

• 命令、子命令或参数变更：更新 docs/en/CLI_User_Guide.md 与 docs/zh/CLI_User_Guide.md。

Agent（attestation_agent）

• 部署、环境或 attester 行为变更：更新 docs/en/attestation_agent.md、docs/zh/attestation_agent.md 及环境准备文档。

Key Manager（key_manager）

• 安装、配置或 mTLS 变更：更新 docs/en/key_manager_install.md 与 docs/zh/key_manager_install.md。

项目与维护者文档

按变更类型更新对应文档，并与代码、scripts/ 保持一致：

变更类型	更新位置
AI/贡献者速查、workspace 布局、命名、构建命令摘要	AGENTS.md（保持简短；流程细节放在本文件与 docs/，避免重复长文）
架构、组件边界、设计决策	docs/zh/architecture.md（英文：docs/en/architecture.md）
本地构建、安装、Docker、RPM	docs/en/GTA_Usage_Guidelines.md、docs/zh/GTA_Usage_Guidelines.md、rpm/spec/
仓库入口与快速链接	README.md
贡献流程本身	本文件 CONTRIBUTING.md（中英文同步）

上述维护者文档（除本文件外）须使用英文（docs/zh/ 为对应中文版本）。仅改文档时，在 MR 中说明已核对文中命令、路径与依赖是否与仓库一致。

7. 运行质量门

提交前请在本地执行以下检查。CI 流水线（scripts/pipeline_code_check.sh）安装原生构建依赖并运行 cargo clippy；不运行 cargo test 或完整 cargo build，合并前须在本地跑通受影响 crate 的测试。

质量门（见上文 §4 代码规范；请在合并前于本地执行）：

cargo fmt
cargo clippy -- --cap-lints warn -W clippy::all -A clippy::restriction

测试（按变更范围选择）：

# 受影响 crate
cargo test --package <package-name>

# 全 workspace（耗时较长；完整原生构建依赖见 §2）
cargo test --workspace

仅文档变更： 使用 doc/ 分支前缀；提交信息如 docs: 或 docs(api):。未改 Rust/脚本时可不新增测试；在 MR 中说明已按文档核对命令与路径。若同期包含代码变更，仍须完整质量门与相应测试。

要求： 合并前 cargo fmt、cargo clippy 须通过，且受影响 crate 的 cargo test 须通过。

8. 提交变更

提交信息须清晰、简洁、具描述性，采用 Conventional Commits 风格，与现有历史一致（如 feat:、fix:、docs:、refactor:、test:）。

本仓库在 GitCode 合入 Merge Request 后，提交历史可能出现 !NN 前缀（如 !340）——由平台自动添加。请勿在分支名或 commit message 中手动写入 !NN。

示例：

git add .
git commit -m "fix: validate REST config before startup (fixes #42)"

9. 推送变更

将新分支推送到您 fork 的仓库：

git push origin feature/your-feature-name

10. 创建 Merge Request (MR)

从您 fork 的分支向主仓库的目标分支（通常为 master）发起 merge request。

详细描述： 包含变更的完整描述、理由以及相关 issue 编号（如 Closes #101）。若变更影响 AGENTS.md § Security-Sensitive Areas 中的安全边界，请显式说明。

检查清单： 建议在 MR 描述中加入如下小型清单：

质量门：

• cargo fmt 已执行
• cargo clippy 通过
• 受影响 crate 的 cargo test 通过

文档：

• API 变更：已更新 docs/en/api_documentation.md 与 docs/zh/api_documentation.md
• Service / Common / CLI / Agent / Key Manager 变更：已按 §6 更新对应中英文文档
• 架构变更：已同步 docs/zh/architecture.md（及英文 docs/en/architecture.md）

其他：

• 已新增/更新测试
• AGENTS.md、README.md 等维护者文档已按 §6 更新且与代码/脚本一致
• 未提交任何密钥

11. 合并前

• 确保所有 CI 检查通过（本地质量门，以及流水线检查）。
• 确保该 Merge Request 经项目维护者评审并通过。
• 采纳所有评审意见。若意见冲突，请与维护者协调达成共识。
• 此后方可请维护者合并该 Merge Request。

报告安全问题

请遵循 openEuler 漏洞报告指南，将安全问题发送至 openeuler-security@openeuler.org。请勿在公开 issue 中披露未修复的漏洞细节。

语言

本文档以中英文双语表述；如果两个版本存在冲突或不一致，以英文版为准。

---

Contributing

Thank you for your interest in contributing to Global Trust Authority (GTA)! We welcome all kinds of contributions, including bug fixes, new features, documentation improvements, attestation plugin implementations, and tests. Following this guide helps keep the review process smooth and efficient.

---

Before You Start

1. Search Existing Work Check the repository issues and merge requests first to see whether someone is already working on the same idea or problem.

2. Discuss Large Changes For major changes or new features, open an issue first and discuss the design, scope, and implementation plan with the maintainers. GTA touches security-sensitive paths such as remote attestation, key management, nonce replay prevention, and token signing (see AGENTS.md § Security-Sensitive Areas and docs/zh/architecture.md / docs/en/architecture.md); design alignment is especially important for changes that affect these boundaries.

3. Read the Agent & Conventions Guide AGENTS.md documents the workspace layout, build commands, naming, test organization, and conventions that every change must respect.

---

How to Contribute

Use the following steps to prepare and submit your contribution.

1. Fork & Clone

Fork the repository to your GitCode account, then clone it locally:

# HTTPS
git clone https://gitcode.com/<your-username>/global-trust-authority.git
# or SSH
git clone git@gitcode.com:<your-username>/global-trust-authority.git
cd global-trust-authority

2. Set Up the Project

See docs/en/GTA_Usage_Guidelines.md for build and installation instructions. Minimum prerequisites:

• Linux x86_64 or aarch64 (macOS and Windows are not primary hosts; use WSL2 or the Docker Compose workflow)
• Rust stable toolchain, MSRV 1.82+ (use rustup if cargo build complains about Cargo.lock)
• openssl, git, cmake, gcc, and related base build tools
• A full native build also needs tpm2-tss-devel, clang, libboundscheck, virtCCA_sdk, virtCCA_sdk-devel, itrustee_sdk, and related packages (see AGENTS.md Build prerequisites and scripts/pipeline_code_check.sh)

You can iterate on individual crates with a standard Rust toolchain, for example:

cargo check --package attestation

Quick start with Docker (service + MySQL + Redis):

docker compose -f docker/docker-compose.yaml up

3. Create a Branch

Create a descriptively named branch for your work. Release branches use the br_feat_* prefix; for day-to-day contributions, use one of these recommended prefixes:

• feature/ for new features.
• fix/ for bug fixes.
• chore/ for maintenance or build-related tasks.
• doc/ for documentation-only changes.
• test/ for test-only changes.

git checkout -b feature/your-feature-name

4. Make Changes

Keep it Focused: Keep each change focused on one concern whenever possible.

Adhere to Standards: Follow the coding style and conventions documented in AGENTS.md. In particular:

• Run cargo fmt — formatting is governed by rustfmt.toml (max_width = 120, Unix newlines).
• Run cargo clippy -- --cap-lints warn -W clippy::all -A clippy::restriction and resolve warnings.
• Every .rs file must keep the project's Mulan PSL v2 license header.
• Do not use unwrap(), expect(), todo!(), or unimplemented!() in production code.
• New or changed IO should be async when practical; keep blocking IO out of hot async request paths and avoid std::sync::Mutex in async contexts.
• Load configuration through config_manager and env_config_parse; never hardcode values.
• Add comments sparingly and only when they clarify non-obvious behavior; keep public API docs current and match the surrounding code style.
• Language Requirement: Code comments and project docs (docs/, AGENTS.md, .sdd/, etc.) must be written in English. Commit messages may mix Chinese and English to match existing history (for example, feat:, fix:, docs:); this bilingual CONTRIBUTING.md is the exception.

Document Code: Keep public APIs documented. Update the docs listed in §6 when REST API, CLI, or agent behavior changes.

Keep Consistent: Ensure documentation, comments, and code implementation stay consistent across AGENTS.md, docs/, .sdd/, test code, build scripts, deployment configs, and related artifacts. Any behavioral change must update all relevant artifacts in the same change. Do not leave stale docs or comments that disagree with the code.

5. Add or Update Tests

GTA relies primarily on Rust unit and integration tests. Cover your change in the appropriate crate:

Layer	Runner	Location
Unit tests	cargo test	In-crate #[cfg(test)] modules
Integration tests	cargo test	Per-crate tests/test_*.rs
Mock plugins	cargo test	Per-crate mock projects (e.g. plugin_manager/tests/mock_plugin_for_service/, attestation_server/attestation/tests/mock_test_attester/)

Prefer public APIs and in-crate #[cfg(test)] modules.

• Service (attestation_server/): Add or update tests under the relevant crate's tests/ for REST handlers, policy engine, or verifier changes.
• Agent (attestation_agent/): Add or update tests for attester or challenge flow changes; use serial_test when hardware such as TPM is involved.
• CLI (attestation_cli): Add integration tests for command or flag changes.
• Key Manager (key_manager): Add tests for key and mTLS changes; fixtures live in key_manager/tests/testdata/.

Examples:

cargo test --package attestation
cargo test --package challenge
cargo test --package attestation test_attestation_chain

When adding a new hardware attestation source, implement both attester and verifier and wire them through agent/server plugin configuration; do not hardcode plugins outside the plugin system (see AGENTS.md § Adding a New Attestation Type).

6. Sync Documentation When Needed

Update the documentation for the component you changed:

REST API (attestation_server)

If you add or modify API endpoints or parameters, update:

• docs/en/api_documentation.md
• docs/zh/api_documentation.md

Keep the English and Chinese API docs aligned.

Service module (attestation_server, non-REST)

• For service component, runtime flow, or module boundary changes, update docs/en/attestation_service.md and docs/zh/attestation_service.md.

Common infrastructure (attestation_common)

• For cache, database, messaging, or other shared crate changes, update docs/en/attestation_common.md and docs/zh/attestation_common.md.

CLI (attestation_cli)

• For command, subcommand, or flag changes, update docs/en/CLI_User_Guide.md and docs/zh/CLI_User_Guide.md.

Agent (attestation_agent)

• For deployment, environment, or attester behavior changes, update docs/en/attestation_agent.md, docs/zh/attestation_agent.md, and the environment preparation guides.

Key Manager (key_manager)

• For install, configuration, or mTLS changes, update docs/en/key_manager_install.md and docs/zh/key_manager_install.md.

Project & maintainer docs

Update the relevant documentation and keep it aligned with code and scripts/:

Change type	Where to update
AI/contributor quick reference, workspace layout, naming, build command summary	AGENTS.md (keep it short; put procedures in this file and docs/ — do not duplicate long guides)
Architecture, component boundaries, design decisions	docs/zh/architecture.md (EN: docs/en/architecture.md)
Local build, install, Docker, RPM	docs/en/GTA_Usage_Guidelines.md, docs/zh/GTA_Usage_Guidelines.md, rpm/spec/
Repository entry point and quick links	README.md
This contribution workflow	CONTRIBUTING.md (keep Chinese and English in sync)

The maintainer documents listed above, except this file, must be written in English (docs/zh/ holds the corresponding Chinese versions). For documentation-only MRs, state in the MR description that you checked the documented commands, paths, and dependencies against the repository.

7. Run Quality Gates

Run the following checks locally before submission. The CI pipeline (scripts/pipeline_code_check.sh) installs native build dependencies and runs cargo clippy. It does not run cargo test or a full cargo build — you must pass tests for affected crates locally before merge.

Quality gates (see §4 Make Changes above; run them locally before merge):

cargo fmt
cargo clippy -- --cap-lints warn -W clippy::all -A clippy::restriction

Tests (scope to your change):

# Affected crate
cargo test --package <package-name>

# Full workspace (slow; see §2 for native build dependencies)
cargo test --workspace

Docs-only changes: Use a doc/ branch prefix; commit messages such as docs: or docs(api):. No new tests are required when Rust and scripts are untouched. State in the MR that you verified the documented commands and paths. If code changes land in the same MR, the full quality gates and relevant tests still apply.

Requirement: cargo fmt, cargo clippy, and cargo test for affected crates must pass before merging.

8. Commit Your Changes

Write clear, concise, descriptive commit messages using Conventional Commits style. Match the existing history (for example, feat:, fix:, docs:, refactor:, test:).

After a GitCode Merge Request is merged, the commit history may show an !NN prefix (for example !340); the platform adds this automatically. Do not put !NN in branch names or commit messages yourself.

Example:

git add .
git commit -m "fix: validate REST config before startup (fixes #42)"

9. Push Your Changes

Push your new branch to your fork:

git push origin feature/your-feature-name

10. Create a Merge Request (MR)

Open a merge request from your forked branch to the main repository's target branch (usually master).

Detailed Description: Include a complete description of your changes, the rationale behind them, and any relevant issue numbers (for example, Closes #101). Call out any change that affects the security boundaries in AGENTS.md § Security-Sensitive Areas.

Checklist: Consider including this short checklist in your MR description:

Quality gates:

• cargo fmt was run
• cargo clippy passes
• cargo test passes for affected crates

Documentation:

• API changes: docs/en/api_documentation.md and docs/zh/api_documentation.md updated
• Service / Common / CLI / Agent / Key Manager changes: corresponding EN/ZH docs updated per §6
• Architecture changes: docs/zh/architecture.md synchronized (and docs/en/architecture.md)

Other:

• Tests added / updated
• Maintainer docs (AGENTS.md, README.md, etc.) are updated per §6 and aligned with code/scripts
• No secrets / keys committed

11. Before Merge

• Ensure all CI checks pass (local quality gates plus pipeline checks).
• Ensure the Merge Request is reviewed and approved by project maintainers.
• Address all review comments. If comments conflict, coordinate with maintainers to reach consensus.
• Only then request maintainers to merge the Merge Request.

Reporting Security Issues

Follow the openEuler vulnerability reporting guidelines and report security issues to openeuler-security@openeuler.org. Do not disclose unfixed vulnerability details in public issues.

Language

This document is written in both Chinese and English. If the two versions conflict or diverge, the English version prevails.