# 红山开源平台开源项目使用手册
## 1. 开源项目：项目管理

项目是用户创建的对应于一个小组或团队的协同实践社区，由项目管理员、开发人员和报告人员组成，提供问题跟踪、版本管理、里程碑、代码质量分析、资源托管、交流研讨等功能。

注意：未开展分组作业或项目开发的用户暂不涉及本章内容。

### 1.1 基本操作流程

开源项目是一种协同实践社区，支持团队和小组开展各种协作活动。 开源项目的典型操作流程如下： 

1. 项目创建：团队（或小组）的核心成员首先创建一个项目。 

2. 成员添加：通知团队其他成员在红山开源平台上注册（如已注册则忽略此步），将团队成员加入项目。

3. 问题跟踪：发布不同类型的问题，指派给责任人，并跟踪问题的解决进度。

4. 版本管理：基于Git版本库实现分布式版本控制。 

5. 交流互动：基于讨论区等工具开展深度技术交流和研讨。 上述步骤的详细操作参见以下章节。

### 1.2 项目创建 

项目包括创建：1、创建镜像项目；2、创建托管项目；3、创建组织。

1、创建镜像项目 点击右上角“⊕”，选择“创建镜像项目”，如下图所示： ![创建镜像项目](./static/img/3266.png) 填写项目基本信息，包括项目拥有者、镜像版本库地址、项目名称、项目简介等信息，并点击“创建项目”如下图所示： ![img](./static/img/3267.png)

2、创建托管项目 点击右上角“⊕”，选择“创建托管项目”，如下图所示： ![img](./static/img/3239.png) 填写项目基本信息，包括项目拥有者、项目名称、项目简介等信息，并点击“创建项目”如下图所示： ![img](./static/img/3240.png)

3、创建组织 点击右上角“⊕”，选择“创建组织”，如下图所示： ![img](./static/img/3241.png) 填写组织基本信息，包括组织名称、组织描述等，选择可见性，并上传头像后，点击“创建组织”如下图所示： ![img](./static/img/3242.png)

### 1.3 项目配置

项目的管理员可以对项目进行多种配置。 可配置的内容主要包括：

1. 项目基本信息：包括项目名称和简介，还包括项目是否公开、是否隐藏项目代码库以及删除项目

2. 成员管理：为项目添加各种角色的成员，点击“成员”标签页

3. 关联组织：将项目关联到相应的组织，点击“组织”标签页

4. 创建里程碑：为项目创建阶段性的产品版本，点击“里程碑”标签页 

5. 创建版本库：为项目创建版本库（Git），点击“版本库”标签页

### 1.4 成员管理 

项目管理员可以在项目配置中管理项目的成员。 

1、点击“仓库设置”，进入标签页，选择左侧菜单栏的“协作者管理”，将看到如下页面： ![img](./static/img/3243.png) 2、在下图所示的搜索框内输入欲添加成员的用户名，如下图所示： ![img](./static/img/3244.png) 3、在搜索结果中选择想要添加的成员，点击“添加成员”，如下图所示： ![img](./static/img/3245.png) 4、成员添加成功后，可为其选择角色，包括管理员、开发者、报告者三种，如下图所示： ![img](./static/img/3246.png) 注意：项目成员的不同角色具有不同权限。 管理员：可以对项目中的所有模块进行操作。 开发者：不能对项目进行配置。 报告者：不能对版本库进行操作。

### 1.5 删除项目 

管理员可以删除项目。步骤如下： 点击“仓库设置”，进入标签页，选择左侧菜单栏的“基本设置”，点击下方的“删除本仓库”，即可删除当前项目。 ![img](./static/img/3247.png)

### 1.6 发布问题 

1、点击“易修(Issue)”，进入标签页，点击页面右侧的“创建任务”。 ![img](./static/img/3260.png) 2、填写任务标题及内容，选择指派成员、状态、类型、优先度等，点击“创建”。 ![img](./static/img/3251.png) ![img](./static/img/3252.png) ![img](./static/img/3253.png) ![img](./static/img/3254.png) ![img](./static/img/3255.png) 3、出现如下图所示信息时，表明问题发布成功。 ![img](./static/img/3256.png) 4、点击已发布的问题，进入问题详情页面，点击下图所示的评论区输入栏。 ![img](./static/img/3257.png) 5、点开输入栏后出现下图所示输入界面，输入想要评论的内容后，点击“评论”。 ![img](./static/img/3258.png) 6、出现如下图所示信息时，表明评论成功。 ![img](./static/img/3259.png) 注意： 每个问题都相当于一个可以进度追踪的帖子。因此支持回复、点赞、@等。 在问题截止日期的前一天，系统将对问题的发布人和被指派人发送提示消息。

### 1.7 新建里程碑 

管理员可以新建里程碑。步骤如下： 1、点击“里程碑”，进入标签页，点击页面右侧的“新建里程碑”。 ![img](./static/img/3261.png) 2、填写新里程碑相关信息，包括标题、描述等，选择截止日期后，点击“创建里程碑”。 ![img](./static/img/3262.png) 3、出现如下图所示信息时，表明新的里程碑创建成功。 ![img](./static/img/3263.png) 注意：项目成员在发布问题时。将在“目标版本”属性中看到新建的版本。

### 1.8 关联里程碑 

项目成员可以将项目问题关联到里程碑，从而使里程碑包含明确的任务列表。 步骤如下： 1、进入某个问题的页面，编辑“里程碑”属性，从“里程碑”下拉框中选择适当的里程碑，点击“提交”。 ![img](./static/img/3264.png) 2、出现如下图所示信息时，表明里程碑关联成功。 ![img](./static/img/3265.png)

## 2. 开源项目：组织管理
为了满足团队开发、协作、宣传和管理需要，红山开源提供了组织功能。 
### 2.1 组织创建
1. 在用户登录状态下，点击右上角用户头像，选择开源主页。
![img](./static/img/9999.jpg)
2. 进入开源主页后，点击组织按钮
![img.png](./static/img/img.png)
3. 点击新建组织，跳转至新建组织页面并输入组织相关信息，输入完成后点击创建组织进行创建
![img.png](./static/img/9997.png)
![img.png](./static/img/9996.png)

### 2.2 组织页面配置及介绍

在`2.1 组织创建`点击创建组织后，网站将自动跳转至组织页面。

![image-20220805093839705](./static/img/4000.png)

点击组织页面右上角设置按钮进入组织页面配置页面

![image-20220805094357904](./static/img/4001.png)

组织设置共分为四个模块：基本设置、组织首页管理、组织成员管理、组织团队管理

![image-20220805094500603](./static/img/image-20220805094500603.png)

1. 基本设置

   在组织配置的基本设置中，可对当前组织的组织名称、组织描述、官方网站、所在地区、可见性、权限、最大仓库数、组织头像（推荐上传正方形图片）进行修改。

   其中，组织名称、组织描述、可见性、组织头像为必填项，其余为选填项；用户可根据自身需求进行相关的编辑及修改。

2. 组织首页管理

   在组织首页管理当中，主要可对两个部分进行相应配置：新闻动态、组织介绍（均不是必填项，若不填写 组织页面将进行隐藏显示）。

   其中新闻动态图片推荐大小为288*120

   + 新闻动态
     + 新闻动态图片  大小288*120
     + 新闻动态原文链接，此处可以填写相应的网站链接。用户点击新闻即可进行跳转
     + 新闻动态标题，此处为新闻的标题信息
     + 新闻动态内容，此处为新闻的动态内容，最多可输入200字
   + 组织介绍
     + 此处为组织介绍，需填写组织的相关信息。支持markdown语法

   ![image-20220805095532236](./static/img/image-20220805095532236.png)

3. 组织成员管理

   组织成员管理页面可查看、添加、删除组织的成员。

   + 点击右上角`添加成员`进行人员添加（需要选择添加人员的组织团队）

     ![image-20220805101149075](./static/img/image-20220805101149075.png)

     选择组织团队之后跳转至人员添加页面，点击右上角搜索框，输入需要添加的用户名对平台用户进行搜索

     ![image-20220805101655892](./static/img/image-20220805101655892.png)

     点击对应用户，点击右侧按钮`添加成员`进行人员添加。

     

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`

注：后续我们将列出更多的错误解决办法。