306 lines
16 KiB
Markdown
306 lines
16 KiB
Markdown
# 红山开源平台开源项目使用手册
|
||
## 1. 开源项目：项目管理
|
||
|
||
项目是用户创建的对应于一个小组或团队的协同实践社区，由项目管理员、开发人员和报告人员组成，提供问题跟踪、版本管理、里程碑、代码质量分析、资源托管、交流研讨等功能。
|
||
|
||
注意：未开展分组作业或项目开发的用户暂不涉及本章内容。
|
||
|
||
### 1.1 基本操作流程
|
||
|
||
开源项目是一种协同实践社区，支持团队和小组开展各种协作活动。 开源项目的典型操作流程如下：
|
||
|
||
1. 项目创建：团队（或小组）的核心成员首先创建一个项目。
|
||
|
||
2. 成员添加：通知团队其他成员在红山开源平台上注册（如已注册则忽略此步），将团队成员加入项目。
|
||
|
||
3. 问题跟踪：发布不同类型的问题，指派给责任人，并跟踪问题的解决进度。
|
||
|
||
4. 版本管理：基于Git版本库实现分布式版本控制。
|
||
|
||
5. 交流互动：基于讨论区等工具开展深度技术交流和研讨。 上述步骤的详细操作参见以下章节。
|
||
|
||
### 1.2 项目创建
|
||
|
||
项目包括创建：1、创建镜像项目；2、创建托管项目；3、创建组织。
|
||
|
||
1、创建镜像项目 点击右上角“⊕”，选择“创建镜像项目”，如下图所示：  填写项目基本信息，包括项目拥有者、镜像版本库地址、项目名称、项目简介等信息，并点击“创建项目”如下图所示： 
|
||
|
||
2、创建托管项目 点击右上角“⊕”，选择“创建托管项目”，如下图所示：  填写项目基本信息，包括项目拥有者、项目名称、项目简介等信息，并点击“创建项目”如下图所示： 
|
||
|
||
3、创建组织 点击右上角“⊕”，选择“创建组织”，如下图所示：  填写组织基本信息，包括组织名称、组织描述等，选择可见性，并上传头像后，点击“创建组织”如下图所示： 
|
||
|
||
### 1.3 项目配置
|
||
|
||
项目的管理员可以对项目进行多种配置。 可配置的内容主要包括：
|
||
|
||
1. 项目基本信息：包括项目名称和简介，还包括项目是否公开、是否隐藏项目代码库以及删除项目
|
||
|
||
2. 成员管理：为项目添加各种角色的成员，点击“成员”标签页
|
||
|
||
3. 关联组织：将项目关联到相应的组织，点击“组织”标签页
|
||
|
||
4. 创建里程碑：为项目创建阶段性的产品版本，点击“里程碑”标签页
|
||
|
||
5. 创建版本库：为项目创建版本库（Git），点击“版本库”标签页
|
||
|
||
### 1.4 成员管理
|
||
|
||
项目管理员可以在项目配置中管理项目的成员。
|
||
|
||
1、点击“仓库设置”，进入标签页，选择左侧菜单栏的“协作者管理”，将看到如下页面：  2、在下图所示的搜索框内输入欲添加成员的用户名，如下图所示：  3、在搜索结果中选择想要添加的成员，点击“添加成员”，如下图所示：  4、成员添加成功后，可为其选择角色，包括管理员、开发者、报告者三种，如下图所示：  注意：项目成员的不同角色具有不同权限。 管理员：可以对项目中的所有模块进行操作。 开发者：不能对项目进行配置。 报告者：不能对版本库进行操作。
|
||
|
||
### 1.5 删除项目
|
||
|
||
管理员可以删除项目。步骤如下： 点击“仓库设置”，进入标签页，选择左侧菜单栏的“基本设置”，点击下方的“删除本仓库”，即可删除当前项目。 
|
||
|
||
### 1.6 发布问题
|
||
|
||
1、点击“易修(Issue)”，进入标签页，点击页面右侧的“创建任务”。  2、填写任务标题及内容，选择指派成员、状态、类型、优先度等，点击“创建”。      3、出现如下图所示信息时，表明问题发布成功。  4、点击已发布的问题，进入问题详情页面，点击下图所示的评论区输入栏。  5、点开输入栏后出现下图所示输入界面，输入想要评论的内容后，点击“评论”。  6、出现如下图所示信息时，表明评论成功。  注意： 每个问题都相当于一个可以进度追踪的帖子。因此支持回复、点赞、@等。 在问题截止日期的前一天，系统将对问题的发布人和被指派人发送提示消息。
|
||
|
||
### 1.7 新建里程碑
|
||
|
||
管理员可以新建里程碑。步骤如下： 1、点击“里程碑”，进入标签页，点击页面右侧的“新建里程碑”。  2、填写新里程碑相关信息，包括标题、描述等，选择截止日期后，点击“创建里程碑”。  3、出现如下图所示信息时，表明新的里程碑创建成功。  注意：项目成员在发布问题时。将在“目标版本”属性中看到新建的版本。
|
||
|
||
### 1.8 关联里程碑
|
||
|
||
项目成员可以将项目问题关联到里程碑，从而使里程碑包含明确的任务列表。 步骤如下： 1、进入某个问题的页面，编辑“里程碑”属性，从“里程碑”下拉框中选择适当的里程碑，点击“提交”。  2、出现如下图所示信息时，表明里程碑关联成功。 
|
||
|
||
## 2. 开源项目：组织管理
|
||
为了满足团队开发、协作、宣传和管理需要，红山开源提供了组织功能。
|
||
### 2.1 组织创建
|
||
1. 在用户登录状态下，点击右上角用户头像，选择开源主页。
|
||
|
||
2. 进入开源主页后，点击组织按钮
|
||
|
||
3. 点击新建组织，跳转至新建组织页面并输入组织相关信息，输入完成后点击创建组织进行创建
|
||
|
||
|
||
|
||
### 2.2 组织页面配置及介绍
|
||
|
||
在`2.1 组织创建`点击创建组织后，网站将自动跳转至组织页面。
|
||
|
||
|
||
|
||
点击组织页面右上角设置按钮进入组织页面配置页面
|
||
|
||
|
||
|
||
组织设置共分为四个模块：基本设置、组织首页管理、组织成员管理、组织团队管理
|
||
|
||
|
||
|
||
1. 基本设置
|
||
|
||
在组织配置的基本设置中，可对当前组织的组织名称、组织描述、官方网站、所在地区、可见性、权限、最大仓库数、组织头像（推荐上传正方形图片）进行修改。
|
||
|
||
其中，组织名称、组织描述、可见性、组织头像为必填项，其余为选填项；用户可根据自身需求进行相关的编辑及修改。
|
||
|
||
2. 组织首页管理
|
||
|
||
在组织首页管理当中，主要可对两个部分进行相应配置：新闻动态、组织介绍（均不是必填项，若不填写 组织页面将进行隐藏显示）。
|
||
|
||
其中新闻动态图片推荐大小为288*120
|
||
|
||
+ 新闻动态
|
||
+ 新闻动态图片 大小288*120
|
||
+ 新闻动态原文链接，此处可以填写相应的网站链接。用户点击新闻即可进行跳转
|
||
+ 新闻动态标题，此处为新闻的标题信息
|
||
+ 新闻动态内容，此处为新闻的动态内容，最多可输入200字
|
||
+ 组织介绍
|
||
+ 此处为组织介绍，需填写组织的相关信息。支持markdown语法
|
||
|
||
|
||
|
||
3. 组织成员管理
|
||
|
||
组织成员管理页面可查看、添加、删除组织的成员。
|
||
|
||
+ 点击右上角`添加成员`进行人员添加（需要选择添加人员的组织团队）
|
||
|
||
|
||
|
||
选择组织团队之后跳转至人员添加页面，点击右上角搜索框，输入需要添加的用户名对平台用户进行搜索
|
||
|
||
|
||
|
||
点击对应用户，点击右侧按钮`添加成员`进行人员添加。
|
||
|
||
|
||
|
||
4. 组织团队管理
|
||
|
||
|
||
|
||
## 3. 开源项目：版本管理
|
||
|
||
版本管理又称版本控制，是一种分布式协同编程的重要工具。没有掌握好版本管理工具，团队式协同开发是不可想象的。
|
||
|
||
红山开源平台集成了Gitlab版本管理系统，可以提供标准的Git版本库操作流程。 因此，在使用本平台提供的Git仓库时。可以直接参考本手册。也可以在互联网中搜索相关问题的解决方法。 详见：Git使用指南（https://git-scm.com/book/zh/v2）
|
||
|
||
注意：未开展项目开发的用户暂不涉及本章内容。
|
||
|
||
### 3.1 基本操作流程
|
||
|
||
Git版本库的使用非常灵活，功能非常强大，但其基本流程也是非常简单的：
|
||
|
||
1. 在平台上新建远程版本库或fork一个远程版本库
|
||
|
||
2. 将远程库clone到本地
|
||
|
||
3. 在本地库中创建分支（缺省为master）
|
||
|
||
4. 提交（commit）代码到本地分支
|
||
|
||
5. 推送（push）代码到远程库的分支/下拉（pull）远程库的代码到本地
|
||
|
||
6. 解决冲突
|
||
|
||
7. 合并分支
|
||
|
||
以上是一个在实际操作中反复进行的基本流程。
|
||
|
||
注意： 在多人协同编程的情况下，每个成员在开发自己的模块时，尽可能先从master或developer分支下载最新代码，并与本地分支合并，否则时间久了，合并分支将是一个灾难。 上连基本流程可以使用Git命令行客户端、Tortoise Git客户端等工具完成。
|
||
|
||
### 3.2 fork版本库
|
||
|
||
用户对某一个版本库的fork操作将会为该用户创建一个同名项目和同名版本库。
|
||
|
||
操作步骤：进入需要fork的版本库页面，点击右上角的Fork按钮即可。
|
||
|
||
注意： 任何用户都可以fork一个公开的版本库。 连续两次fork同一版本时，系统将直接跳转到第一次fork后的版本库。
|
||
|
||
### 3.3 新建版本库
|
||
|
||
管理员可以新建版本库。步骤如下:
|
||
|
||
1. 进入相应的开源项目的“项目配置”页面
|
||
2. 点击“版本库”标签页，点击“新建版本库”链接
|
||
3. 填写版本库名称后，点击“创建”
|
||
|
||
注意： 同一用户名下的版本不能重名。 平台也将在近期提供SSH访问方式。
|
||
|
||
### 3.4 克隆版本库(clone)
|
||
|
||
克隆版本库是将开源项目的版本库完整的克隆到本地的过程。其中包括了版本库的所有提交记录。步骤如下：
|
||
|
||
1. 确定需要克隆的版本库地址：从项目的版本库页面中即可找到该地址
|
||
|
||
2. 在本地的git命令行执行：
|
||
|
||
```bash
|
||
git clone https://git.osredm.com/xxx/yyy.git
|
||
```
|
||
|
||
其中“https:// git.osredm.com /xxx/yyy.git”是版本库的地址，xxx为用户ID，yyy为项目名称
|
||
|
||
3. 如果项目是私有的，根据提示输入版本库用户名和密码，输入当前用户的红山开源平台登录名和密码即可
|
||
|
||
注意：如果项目公开, 无需输入口令, 可以直接克隆。 对于私有项目，只有项目成员才具有克隆的权限。
|
||
|
||
### 3.5 新建分支、切换分支
|
||
|
||
+ 新建分支
|
||
|
||
新建分支是指在本地库创建一个新的分支（用于开发新的功能），并且将其同步到远程库。主要步骤如下:
|
||
|
||
1. 从已有的分支创建新的分支（如从master分支），例如创建一个dev分支： `git checkout -b dev`
|
||
|
||
2. 创建后可以查看一下当前分支，确认当前分支已经切换到dev： `git branch dev master`
|
||
|
||
3. 提交该新的分支到远程仓库: `git push origin dev:devl`
|
||
|
||
其中: dev为本地新建分支:devl为远程分支，如果devl不存在则会自动创建分支。这里，dev应该等于devl。
|
||
|
||
+ 切换分支
|
||
|
||
切换分支是指将当前工作分支换为另一个分支 。假设，本地仓库有master和dev两个分支，当前分支是master（其实也可以是其他分支）。那么切换到dev分支的命令是： `git checkout dev`
|
||
|
||
注意：用户可以使用git branch命令确认当的分支是否已经切换到dev
|
||
|
||
### 3.6 提交代码(commit)
|
||
|
||
项目成员在本地编辑代码或修改文件后，可以将新修改的文件提交到本地库:
|
||
|
||
1. 将新修改的所有文件添加到本地版本库的暂存区（stage）： `git add .`
|
||
|
||
注意：如果仅添加单个文件，或一类文件，可以： `git add somefile.txt #添加单个文件`
|
||
|
||
2. 将提交到暂存区的修改提交到本地的当前分支： `git commit -m “myfirstcommit”`
|
||
|
||
其中，“mycommit”中的内容是关于本次提交的说明文字。
|
||
|
||
注意：commit只能将修改的文件提交到本地库，与远程库没有关系。
|
||
|
||
### 3.7 推送代码(push)
|
||
|
||
项目成员可以将本地提交后的改动，推送到远程库。
|
||
|
||
假设用户需要将本地库的dev分支推送至远程库的dev分支，执行： `git push -u origin dev `
|
||
|
||
如果用户的当前的本地分支己经是dev, 那么执行: `git push`
|
||
|
||
如果用户需要将本地的全部分支推送到远程库。那么执行： `git push -all origin`
|
||
|
||
注意： push代码时会提示输入用户密码，请输入红山开源平台登录名和密码即可。 Push代码之前通常要先pull，解决冲突后才能提交，否则不是最新的文件就提交不上去。
|
||
|
||
### 3.8 下拉代码(pull)
|
||
|
||
下拉代码是指从远程版本库获取代码文件到本地分支。
|
||
|
||
例如，用户希望将远程版本库的devl分支下拉到本地的dev分支，需要执行： `git pull origin dev devl`
|
||
|
||
注意：下拉代码时可能会出现冲突（即两个分支对同一个文件的同一行代码做了不同的修改）。此时常利用merge来解决冲突。
|
||
|
||
### 3.9 合并分支(merge)
|
||
|
||
合并分支是指将一个分支合并到当前分支。通常有两种情况：
|
||
|
||
1. 将一个本地分支合并到当前分支：
|
||
|
||
例如，假设用户希望将本地库的devl分支合并到当前分支dev ,命令如下: `git merge dev1`
|
||
|
||
2. 将一个远程库的分支合并到当前分支：
|
||
|
||
例如，假设用户希望将远程库的devl分支合并到当前分支dev,有多种方法，这里仅给出最基本的：
|
||
|
||
```bash
|
||
git checkout -b temp #新建一个临时分支temp
|
||
git pull origin dev1:temp #将远程devl分支下拉到temp分支
|
||
git checkout dev #切换到本地dev分支
|
||
git merge temp #合并分支(可能 产生冲突，合并完成后，应删除temp分支)
|
||
```
|
||
|
||
注意:合并分支可能会出现冲突（即两个分支对同一个文件的同一行代码做了不同的修改）。
|
||
|
||
### 3.10 解决冲突
|
||
|
||
冲突是两次不同的提交修改了同一行代码导致的，通常表现为两个分支对同一行代码做了不同的修改。 版本冲突主要出现在以下两种情况：
|
||
|
||
第一种情况：在对远程版本库进行pull操作时。
|
||
|
||
第二种情况：对本地版本库的不同分支进行merge操作时。
|
||
|
||
解决冲突的主要方法有两种：
|
||
|
||
1. 对于简单的冲突，直接修改有冲突的文件，然后重新提交即可
|
||
2. 对于复杂的冲突，需要用**git merge tool**来解决。 复杂的冲突解决方法(基于git merge tool)将在近期提供给大家
|
||
|
||
### 3.11 常见错误
|
||
|
||
新手在使用Git时经常遇到各种错误，由于平台集成的是标准Git服务(Gitlab)，建议大家可以直接在互联网搜索疑难问题的解决办法。 或参考Git使用手册： https://git-scm.com/book/zh/v2 为给大家提供方便，这里先列出一种最常见的错误：
|
||
|
||
错误1:
|
||
|
||
```bash
|
||
fatal:The remote end hung up unexpectedly
|
||
```
|
||
|
||
|
||
|
||
Windows环境解决方法，在.git/config文件中加入： `[http] postBuffer = 524288000`
|
||
|
||
Linux环境解决方法，在命令行执行： `git config http.postBuffer 524288000`
|
||
|
||
注：后续我们将列出更多的错误解决办法。
|