osredm_help/README.md

红山开源平台开源项目使用手册

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命令行执行：

   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,有多种方法，这里仅给出最基本的：

   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:

fatal:The remote end hung up unexpectedly 

Windows环境解决方法，在.git/config文件中加入： [http] postBuffer = 524288000

Linux环境解决方法，在命令行执行： git config http.postBuffer 524288000

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

4. 致谢

红山开源平台的不断发展主要归功于平台的用户页献者群体。他们不仅是使用者，也是设计者、体验者和测试者，他们为平台献策献力，极大拓展了开发团队的视野、提高了开发团队的效率。可以说，没有他们的页献就没有大家看到的红山开源社区。

如有疏漏请指正，我们将及时更新。