增加文档
This commit is contained in:
rw0067680
@@ -64,4 +64,3 @@ docs/
|
||||
---
|
||||
|
||||
**开始编写你的文档吧！** 📝
|
||||
|
||||
|
||||
1258
docs/学习笔记/MkDocs 是什么.md
Normal file
1258
docs/学习笔记/MkDocs 是什么.md
Normal file
File diff suppressed because it is too large
Load Diff
424
docs/学习笔记/gerrit上传代码详细指南.md
Normal file
424
docs/学习笔记/gerrit上传代码详细指南.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# gerrit上传代码详细指南
|
||||
|
||||
# **Gerrit 代码上传详细指南**
|
||||
|
||||
## **一、Gerrit 工作流程概述**
|
||||
|
||||
```
|
||||
开发者 → 本地开发 → 推送代码审查 → Gerrit 评审 → 评审通过 → 合并代码
|
||||
↑ ↓
|
||||
└─────────────── 需要修改 ← 评审不通过 ←───────────────┘
|
||||
```
|
||||
|
||||
## **二、环境准备**
|
||||
|
||||
### **1. 安装必要的工具**
|
||||
|
||||
```bash
|
||||
# 安装 Git
|
||||
sudo apt-get install git # Ubuntu/Debian
|
||||
brew install git # macOS
|
||||
|
||||
# 安装 commit-msg 钩子（关键步骤）
|
||||
curl -Lo .git/hooks/commit-msg http://YOUR_GERRIT:8080/tools/hooks/commit-msg
|
||||
chmod +x .git/hooks/commit-msg
|
||||
```
|
||||
|
||||
### **2. 配置 Git 用户信息**
|
||||
|
||||
```bash
|
||||
git config --global user.name "你的姓名"
|
||||
git config --global user.email "你的邮箱@company.com"
|
||||
git config --global core.autocrlf input # Windows 用户重要！
|
||||
git config --global core.safecrlf warn
|
||||
```
|
||||
|
||||
### **3. 配置 SSH 密钥**
|
||||
|
||||
```bash
|
||||
# 生成 SSH 密钥
|
||||
ssh-keygen -t ed25519 -C "your_email@company.com"
|
||||
|
||||
# 查看公钥
|
||||
cat ~/.ssh/id_ed25519.pub
|
||||
|
||||
# 将公钥添加到 Gerrit: Settings → SSH Keys
|
||||
```
|
||||
|
||||
## **三、日常开发流程**
|
||||
|
||||
### **1. 克隆项目**
|
||||
|
||||
```bash
|
||||
# 方式1：通过 SSH（推荐）
|
||||
git clone ssh://username@gerrit-server:29418/project-name
|
||||
|
||||
# 方式2：通过 HTTP
|
||||
git clone http://gerrit-server:8080/project-name
|
||||
```
|
||||
|
||||
### **2. 创建开发分支**
|
||||
|
||||
```bash
|
||||
# 从 master 创建功能分支
|
||||
git checkout master
|
||||
git pull origin master
|
||||
git checkout -b feature/your-feature-name
|
||||
|
||||
# 或者从特定版本创建
|
||||
git checkout -b feature/xxx release-1.0
|
||||
```
|
||||
|
||||
### **3. 进行开发**
|
||||
|
||||
```bash
|
||||
# 修改文件
|
||||
git add .
|
||||
git status # 查看状态
|
||||
|
||||
# 提交代码（commit-msg 钩子会自动添加 Change-Id）
|
||||
git commit -m "功能描述
|
||||
|
||||
详细描述：
|
||||
1. 做了什么修改
|
||||
2. 为什么修改
|
||||
3. 测试情况
|
||||
|
||||
Bug: BUG-12345 # 如果有 Bug 编号
|
||||
Feature: FEAT-6789 # 如果有需求编号
|
||||
|
||||
Change-Id: I自动生成"
|
||||
```
|
||||
|
||||
### **4. 推送代码审查**
|
||||
|
||||
```bash
|
||||
# 标准推送方式（创建/更新代码审查）
|
||||
git push origin HEAD:refs/for/目标分支
|
||||
|
||||
# 示例：
|
||||
git push origin HEAD:refs/for/master # 推送到 master 评审
|
||||
git push origin HEAD:refs/for/release-1.0 # 推送到 release 分支评审
|
||||
git push origin HEAD:refs/for/feature/xxx # 推送到功能分支评审
|
||||
```
|
||||
|
||||
## **四、推送参数详解**
|
||||
|
||||
### **1. 普通推送**
|
||||
|
||||
```bash
|
||||
# 创建新的代码审查
|
||||
git push origin HEAD:refs/for/master
|
||||
|
||||
# 创建草稿代码审查
|
||||
git push origin HEAD:refs/drafts/master
|
||||
```
|
||||
|
||||
### **2. 推送并设置评审人**
|
||||
|
||||
```bash
|
||||
# 推送并添加 Reviewer
|
||||
git push origin HEAD:refs/for/master%r=reviewer1@company.com,r=reviewer2@company.com
|
||||
|
||||
# 推送并添加 CC
|
||||
git push origin HEAD:refs/for/master%cc=manager@company.com
|
||||
|
||||
# 推送并设置 Topic
|
||||
git push origin HEAD:refs/for/master%topic=feature/login
|
||||
```
|
||||
|
||||
### **3. 推送选项组合**
|
||||
|
||||
```bash
|
||||
# 完整示例
|
||||
git push origin HEAD:refs/for/master%\
|
||||
r=alice@company.com,\
|
||||
r=bob@company.com,\
|
||||
cc=manager@company.com,\
|
||||
topic=feature/login,\
|
||||
l=Code-Review+2,\
|
||||
l=Verified+1
|
||||
```
|
||||
|
||||
## **五、更新已有的代码审查**
|
||||
|
||||
### **1. 修改后更新**
|
||||
|
||||
```bash
|
||||
# 修改代码后
|
||||
git add .
|
||||
git commit --amend # 重要：必须使用 --amend 保留 Change-Id
|
||||
|
||||
# 重新推送（会自动更新原有代码审查）
|
||||
git push origin HEAD:refs/for/master
|
||||
```
|
||||
|
||||
### **2. 基于评审意见修改**
|
||||
|
||||
```bash
|
||||
# 查看评审意见后修改
|
||||
git fetch origin refs/changes/XX/YYYY/Z && git checkout FETCH_HEAD
|
||||
# 或者
|
||||
git review -d 12345 # 如果安装了 git-review
|
||||
|
||||
# 修改代码
|
||||
git add .
|
||||
git commit --amend
|
||||
|
||||
# 重新推送
|
||||
git push origin HEAD:refs/for/master
|
||||
```
|
||||
|
||||
### **3. 创建新的 Patch Set**
|
||||
|
||||
```bash
|
||||
# 每次 git commit --amend 后推送都会创建新的 Patch Set
|
||||
git log --oneline -1 # 确认 Change-Id 存在
|
||||
git push origin HEAD:refs/for/master
|
||||
```
|
||||
|
||||
## **六、解决常见问题**
|
||||
|
||||
### **问题1：缺少 Change-Id**
|
||||
|
||||
```bash
|
||||
# 安装 commit-msg 钩子
|
||||
curl -Lo .git/hooks/commit-msg http://gerrit:8080/tools/hooks/commit-msg
|
||||
chmod +x .git/hooks/commit-msg
|
||||
|
||||
# 为现有提交添加 Change-Id
|
||||
git commit --amend --no-edit # 重新提交，钩子会自动添加
|
||||
|
||||
# 或者手动添加
|
||||
git commit --amend -m "原提交信息
|
||||
|
||||
Change-Id: I旧的ChangeId" # 从 Gerrit 界面复制
|
||||
```
|
||||
|
||||
### **问题2：权限拒绝**
|
||||
|
||||
```bash
|
||||
# 检查 SSH 配置
|
||||
ssh -p 29418 username@gerrit-server
|
||||
|
||||
# 检查公钥是否添加
|
||||
cat ~/.ssh/id_ed25519.pub
|
||||
|
||||
# 检查项目权限
|
||||
# 联系管理员或查看 Gerrit Web 界面
|
||||
```
|
||||
|
||||
### **问题3：冲突无法推送**
|
||||
|
||||
```bash
|
||||
# 拉取最新代码
|
||||
git fetch origin
|
||||
git rebase origin/master # 或者 git merge origin/master
|
||||
|
||||
# 解决冲突
|
||||
git mergetool # 或手动解决
|
||||
git add .
|
||||
git rebase --continue # 如果使用 rebase
|
||||
|
||||
# 重新推送
|
||||
git push origin HEAD:refs/for/master
|
||||
```
|
||||
|
||||
### **问题4：错误的分支目标**
|
||||
|
||||
```bash
|
||||
# 查看当前分支
|
||||
git branch -a
|
||||
|
||||
# 查看远程分支
|
||||
git branch -r
|
||||
|
||||
# 推送到正确的分支
|
||||
git push origin HEAD:refs/for/正确的分支名
|
||||
```
|
||||
|
||||
## **七、高级操作**
|
||||
|
||||
### **1. 提交多个相关修改**
|
||||
|
||||
```bash
|
||||
# 创建多个提交
|
||||
git add file1
|
||||
git commit -m "修改1: 功能A"
|
||||
git add file2
|
||||
git commit -m "修改2: 功能B"
|
||||
|
||||
# 推送到同一个 Topic
|
||||
git push origin HEAD~2:refs/for/master%topic=feature/xxx
|
||||
```
|
||||
|
||||
### **2. 依赖链提交**
|
||||
|
||||
```bash
|
||||
# 第一个提交
|
||||
git commit -m "基础修改"
|
||||
|
||||
# 第二个提交依赖第一个
|
||||
git commit -m "依赖修改"
|
||||
|
||||
# 推送到 Gerrit 时保持依赖关系
|
||||
git push origin HEAD~1:refs/for/master
|
||||
git push origin HEAD:refs/for/master%depends=第一个提交的Change-Id
|
||||
```
|
||||
|
||||
### **3. 使用 git-review 工具**
|
||||
|
||||
```bash
|
||||
# 安装
|
||||
pip install git-review
|
||||
|
||||
# 初始化
|
||||
git review -s
|
||||
|
||||
# 提交代码审查
|
||||
git review
|
||||
|
||||
# 下载代码审查
|
||||
git review -d 12345 # Change-Number
|
||||
```
|
||||
|
||||
## **八、Gerrit Web 界面操作**
|
||||
|
||||
### **1. 查看代码审查**
|
||||
|
||||
- 访问：`http://gerrit:8080`
|
||||
- 登录 → Dashboard → 查看你的代码审查
|
||||
- 点击 Change-Number 进入详情
|
||||
|
||||
### **2. 评审操作**
|
||||
|
||||
- **+1 / -1**：代码风格、建议性意见
|
||||
- **+2 / -2**：代码评审通过/拒绝（需要权限）
|
||||
- **Submit**：合并代码（需要权限）
|
||||
- **Abandon**：放弃代码审查
|
||||
- **Rebase**：重新基于最新代码
|
||||
- **Cherry Pick**：应用到其他分支
|
||||
|
||||
### **3. 查看差异**
|
||||
|
||||
- **Side-by-Side**：并排对比
|
||||
- **Unified Diff**：统一差异
|
||||
- **Patch Set**：切换不同版本
|
||||
|
||||
## **九、最佳实践**
|
||||
|
||||
### **1. 提交信息规范**
|
||||
|
||||
```
|
||||
一句话摘要（50字以内）
|
||||
|
||||
详细描述：
|
||||
• 做了什么修改
|
||||
• 为什么修改
|
||||
• 如何测试
|
||||
• 可能的影响
|
||||
|
||||
Bug: BUG-12345
|
||||
Feature: FEAT-6789
|
||||
Test: 通过单元测试/集成测试
|
||||
|
||||
Change-Id: I自动生成
|
||||
```
|
||||
|
||||
### **2. 代码审查前自查**
|
||||
|
||||
```bash
|
||||
# 1. 运行代码检查
|
||||
git diff --check # 检查空白字符
|
||||
|
||||
# 2. 运行测试
|
||||
npm test # 或 mvn test, pytest 等
|
||||
|
||||
# 3. 检查提交信息
|
||||
git log --oneline -1
|
||||
|
||||
# 4. 确保 Change-Id 存在
|
||||
git log -1 | grep Change-Id
|
||||
```
|
||||
|
||||
### **3. 每日工作流程**
|
||||
|
||||
```bash
|
||||
# 早上
|
||||
git fetch origin
|
||||
git rebase origin/master # 更新本地代码
|
||||
|
||||
# 开发中
|
||||
git add .
|
||||
git commit -m "..."
|
||||
|
||||
# 推送前
|
||||
git pull --rebase origin master # 再次更新
|
||||
解决冲突（如果有）
|
||||
git push origin HEAD:refs/for/master
|
||||
|
||||
# 查看 Gerrit 反馈
|
||||
# 根据评审意见修改
|
||||
```
|
||||
|
||||
## **十、常用命令速查**
|
||||
|
||||
```bash
|
||||
# 初始化
|
||||
git clone ssh://user@gerrit:29418/project
|
||||
scp -p -P 29418 user@gerrit:hooks/commit-msg .git/hooks/
|
||||
|
||||
# 日常开发
|
||||
git checkout -b feature/xxx
|
||||
git add .
|
||||
git commit -m "..."
|
||||
git push origin HEAD:refs/for/master
|
||||
|
||||
# 更新
|
||||
git commit --amend
|
||||
git push origin HEAD:refs/for/master
|
||||
|
||||
# 查看
|
||||
git log --oneline -5
|
||||
git status
|
||||
git diff
|
||||
|
||||
# 解决冲突
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
解决冲突 → git add → git rebase --continue
|
||||
```
|
||||
|
||||
## **十一、故障排除**
|
||||
|
||||
| 问题 | 解决方案 |
|
||||
| ------------- | ----------------- |
|
||||
| 403 Forbidden | 检查 SSH 密钥/HTTP 密码 |
|
||||
| 缺少 Change-Id | 安装 commit-msg 钩子 |
|
||||
| 分支不存在 | 先创建分支或确认分支名 |
|
||||
| 冲突无法推送 | rebase 解决冲突 |
|
||||
| 权限不足 | 联系管理员添加权限 |
|
||||
| 推送被拒绝 | 检查目标分支是否正确 |
|
||||
|
||||
## **十二、快速参考卡片**
|
||||
|
||||
```
|
||||
✅ 正确流程：
|
||||
1. git clone
|
||||
2. 安装 commit-msg 钩子
|
||||
3. git checkout -b feature/xxx
|
||||
4. 开发并提交
|
||||
5. git push origin HEAD:refs/for/目标分支
|
||||
|
||||
✅ 更新流程：
|
||||
1. git commit --amend # 必须！
|
||||
2. git push origin HEAD:refs/for/目标分支
|
||||
|
||||
✅ 关键要点：
|
||||
• 每次提交都必须有 Change-Id
|
||||
• 更新必须用 --amend
|
||||
• 只能推送到 refs/for/
|
||||
• 在 Gerrit Web 界面查看结果
|
||||
```
|
||||
|
||||
|
||||
@@ -13,13 +13,13 @@
|
||||
|
||||
使用三个反引号包裹代码，并指定语言：
|
||||
|
||||
````markdown
|
||||
```markdown
|
||||
```python
|
||||
def hello():
|
||||
print("Hello, World!")
|
||||
```
|
||||
````
|
||||
|
||||
```
|
||||
### 链接
|
||||
|
||||
- 内部链接：使用相对路径
|
||||
@@ -53,6 +53,7 @@ def hello():
|
||||
### 文档头部
|
||||
|
||||
每个文档应包含：
|
||||
|
||||
- 标题（H1）
|
||||
- 简要描述
|
||||
- 目录（可选，用于长文档）
|
||||
@@ -101,4 +102,3 @@ def hello():
|
||||
- 2024-01-01: 初始版本
|
||||
- 2024-01-15: 添加新功能说明
|
||||
```
|
||||
|
||||
|
||||
@@ -26,27 +26,31 @@ docker-compose up -d
|
||||
## 常用命令
|
||||
|
||||
### 启动服务
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### 停止服务
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### 构建静态站点
|
||||
|
||||
```bash
|
||||
docker-compose exec mkdocs mkdocs build
|
||||
```
|
||||
|
||||
### 进入容器
|
||||
|
||||
```bash
|
||||
docker exec -it mkdocs sh
|
||||
```
|
||||
|
||||
|
||||
@@ -20,6 +20,7 @@ mkdocs/
|
||||
### mkdocs.yml
|
||||
|
||||
MkDocs 的主配置文件，包含：
|
||||
|
||||
- 站点信息（名称、描述、作者等）
|
||||
- 主题配置
|
||||
- 插件配置
|
||||
@@ -29,6 +30,7 @@ MkDocs 的主配置文件，包含：
|
||||
### docker-compose.yml
|
||||
|
||||
Docker Compose 配置文件，定义：
|
||||
|
||||
- 使用的镜像
|
||||
- 端口映射
|
||||
- 数据卷挂载
|
||||
@@ -41,4 +43,3 @@ Docker Compose 配置文件，定义：
|
||||
2. **命名规范**: 使用有意义的文件名
|
||||
3. **导航清晰**: 在 `mkdocs.yml` 中维护清晰的导航结构
|
||||
4. **版本控制**: 建议使用 Git 管理文档
|
||||
|
||||
|
||||
@@ -56,4 +56,3 @@
|
||||
## 数据持久化
|
||||
|
||||
所有服务的数据都存储在 Docker 卷中，确保数据持久化。
|
||||
|
||||
|
||||
@@ -158,4 +158,3 @@ sudo chown -R $USER:$USER /home/renjianbo/devops/*/data
|
||||
```bash
|
||||
docker logs <容器名>
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user