diff --git a/README.md b/README.md index 2c9ffbe..5d40519 100644 --- a/README.md +++ b/README.md @@ -1,311 +1,2 @@ -# 红山开源平台开源项目使用手册 -## 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` - -注:后续我们将列出更多的错误解决办法。 - -## 4. 致谢 - -红山开源平台的不断发展主要归功于平台的用户页献者群体。他们不仅是使用者,也是设计者、体验者和测试者,他们为平台献策献力,极大拓展了开发团队的视野、提高了开发团队的效率。可以说,没有他们的页献就没有大家看到的红山开源社区。 - -如有疏漏请指正,我们将及时更新。 \ No newline at end of file diff --git a/_sidebar.md b/_sidebar.md new file mode 100644 index 0000000..0730ec6 --- /dev/null +++ b/_sidebar.md @@ -0,0 +1,4 @@ +- 红山开源平台使用手册 + - [开源项目使用手册](./git.md) + - [创客使用手册](./chuangke.md) + diff --git a/git.md b/git.md new file mode 100644 index 0000000..2c9ffbe --- /dev/null +++ b/git.md @@ -0,0 +1,311 @@ +# 红山开源平台开源项目使用手册 +## 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` + +注:后续我们将列出更多的错误解决办法。 + +## 4. 致谢 + +红山开源平台的不断发展主要归功于平台的用户页献者群体。他们不仅是使用者,也是设计者、体验者和测试者,他们为平台献策献力,极大拓展了开发团队的视野、提高了开发团队的效率。可以说,没有他们的页献就没有大家看到的红山开源社区。 + +如有疏漏请指正,我们将及时更新。 \ No newline at end of file diff --git a/index.html b/index.html index 07eb572..b413db1 100644 --- a/index.html +++ b/index.html @@ -20,12 +20,15 @@ window.$docsify = { //... relativePath: true, - + loadSidebar:true, + subMaxLevel: 5, + sidebarDisplayLevel:5 } + \ No newline at end of file