跳到内容

    • GitLab文档指南

    • 一般的文档:由开发人员负责创建功能．应该在包含代码的合并请求中提交。特性提议(由GitLab贡献者提出)也应该附有相应的文档。它们可以稍后由项目经理和技术作者进行改进。
    • 技术文章:由任何人写GitLab团队成员，GitLab贡献者，或者社区的作家．
    • 每个主题的索引:最初由技术写作团队准备，并由开发人员和项目经理在包含代码的合并请求中保持最新。它们将该主题的所有资源聚集在一个页面中(用户和管理文档、文章和第三方文档)。

    为文档做贡献

    每当一个特性被更改、更新、引入或弃用时，引入这些更改的合并请求必须伴随着文档(更新现有的或创建新的)。当向UI引入更改时，这也是有效的。

    负责编写第一部分文档的人是编写代码的开发人员。产品经理的工作是确保所有功能都随文档一起发布，无论是小的还是大的变化。按照GitLab的发展速度，这是保持文档更新的唯一方法。如果您对此有任何问题，请询问技术写手。否则，当你的内容准备好了，指派他们中的一个为你检查。

    我们使用每月发布博文作为变更记录清单，以确保所有内容都有文档记录。

    每当您提交文档的合并请求时，请使用文档MR描述模板。

    请查阅文档工作流在开始之前。

    文档结构

    • 概述和用例:它是什么，为什么它是必要的，为什么要使用它
    • 要求:我们需要什么开始
    • 教程:如何设置，如何使用

    始终从与主题相关的索引中链接一个新文档，否则，它将不会包含在文档站点搜索中。

    注:待扩展。

    特性概述和用例

    每一个主要的特性(无论在GitLab社区版还是企业版中)都应该在文档的开头呈现两个主要部分:概述而且用例．每个GitLab ee专用功能也应该包含这些部分。

    概述:顾名思义，这里的目标是提供功能的概述。描述一下它是什么，它能做什么，为什么它很重要/很酷/有它很好，它能解决什么问题，用这个功能你能做什么以前不能做的事情。

    用例:为每个主要特性提供至少两个，最好是三个用例。您应该回答这个问题:您可以用这个特性/更改做什么?用例是在现实生活中如何使用该特性或更改的示例。

    例子:

    注意，如果在doc标题(<标题>)和头文件# #概述，您可以省略标题，但保留概述的内容。

    概述而且用例被要求每一个企业版功能，并为每一个主要社区版提供的功能。

    降价和款式

    目前GitLab文档使用Redcarpet作为减价引擎，但是有一个公开讨论在不久的将来实施Kramdown。

    所有的文档都遵循文档风格指南．

    文档目录结构

    文档的结构基于GitLab UI结构本身，由用户，管理员,贡献者．

    为了有一个坚固的站点结构对于我们的文档，所有文档都应该有链接。每个新文档都应该与相关文档交叉链接，并在存在时与主题相关的索引进行链接。

    的目录/流程/，/ gitlab-basics /，/ /大学,/文章/已经被弃用，他们的大部分文档已经在小的迭代中移动到正确的位置。请不要在这些文件夹中创建新的文档。

    位置和命名文件

    通过提供更好的目录布局和组织，可以极大地改进文档层次结构。

    有了一个结构化的文档布局，我们将能够有有意义的url，如docs.gitlab.com/user/project/merge_requests/index.html．使用此模式，您可以立即知道您正在导航与用户相关的文档，并且是关于项目及其合并请求的。

    不要创建类似类型内容的摘要(例如，所有文章，视频等的索引)，而是按主题组织内容(例如，所有与CI相关的内容都放在一起)，并在任何相关内容之间进行交叉链接。

    下表显示了哪种文档放在哪里。

    目录 这里有什么
    doc / user / 与用户相关的文档。任何可以在GitLab UI中完成的事情都可以在这里完成，包括/管理．
    doc /管理/ 需要用户访问安装了GitLab的服务器的文档。可以通过GitLab的界面访问的管理设置在下面doc / user / admin_area /．
    doc / api / API相关文档。
    文档/开发/ 与GitLab开发相关的文档。任何样式指南都应该在这里。
    doc /法律/ 有关向GitLab捐款的法律文件。
    doc /安装/ 可能是访问量最大的目录installation.md就在那里。理想情况下，这个项目应该破产doc /管理/，但最好保持原样，以避免混淆(但仍有争议)。
    doc /更新/ 也一样doc /安装/．应该在管理/但这是一个众所周知的地点，最好保持现状，至少现在是这样。
    doc /主题/ 每个主题的索引(文档/主题/主题名称/ index.md):该主题的所有资源(用户和管理文档、文章和第三方文档)

    一般规则:

    1. 新文档的正确命名和位置，是相关文档的相对URL和用于UX目的的GitLab Map设计的组合(源，图像)．
    2. 创建新文档时，如果文档名称中有多个单词，请确保使用下划线而不是空格或破折号(-)．例如，正确的命名应该是import_projects_from_github.md．同样的规则也适用于图像。
    3. 类型启动一个新目录index.md文件。
    4. 有四个主要目录，用户，政府，api而且发展．
    5. 的doc / user /目录有五个主要子目录:项目/，集团/，配置文件/，仪表板/而且admin_area /．
      1. doc /用户/项目/应包含所有与项目相关的文件。
      2. doc /用户/组/应包含所有与组相关的文档。
      3. / doc / user /概要文件应该包含所有与概要文件相关的文档。你浏览的每一页/配置文件应该有自己的文档，即。account.md，applications.md，emails.md等。
      4. doc / user /仪表板/应该包含所有与仪表板相关的文档。
      5. doc / user / admin_area /应该包含所有与管理相关的文档，描述通过访问GitLab的管理界面(不要混淆文档/管理哪里需要服务器访问)．
        1. 每一个类别/管理/ application_settings应该有自己的文件定位在doc / user / admin_area /设置/．例如，可见性和访问控制类别应该有一个位于doc / user / admin_area /设置/ visibility_and_access_controls.md．
    6. 的doc /主题/目录保存主题相关的技术内容。创建doc /主题/主题名称/ subtopic-name / index.md当需要副标题时。一般用户和管理相关的文档，应该相应地放置。

    如果您不确定文档应该位于何处，您可以ping@axil或@marcia在合并请求中。

    更改文档位置

    更改文档的位置不是一件容易的事。请记住，下面的所有安装都可以使用该文档帮助/不仅仅是GitLab.com或者http://docs.gitlab.com．确保事先与文档团队讨论过这个问题。

    如果你确实需要改变一个文档的位置，不要删除旧文档，而是用新的行替换它的所有内容:

    该文档被移动到[另一个位置](路径/to/new_doc.md)。

    在哪里路径/ / new_doc.md是否是根目录的相对路径文档/．

    例如，如果你要移动文档/工作流/ lfs / lfs_administration.md来doc /政府/ lfs.md，则步骤为:

    1. 复制文档/工作流/ lfs / lfs_administration.md来doc /政府/ lfs.md

    2. 替换以下内容文档/工作流/ lfs / lfs_administration.md:

      此文档已移动到[另一个位置](../../administration/lfs.md)。

    3. 找到旧位置并用新位置替换旧位置。一个快速找到它们的方法是使用git grep．文件克隆的根目录gitlab-ce存储库，然后做:

      Git grep -n "workflow/lfs/lfs_administration"Git grep -n "lfs/lfs_administration"

    注意:注意:如果要移动的文档上有任何Disqus注释，则需要遵循文档中的额外步骤下面．

    注意事项:

    • 由于我们也使用内联文档，除了文档本身，文档也可以在GitLab (app /)，供参观时使用/帮助，有时在测试套件中(规范/)．
    • 上面的git grep命令将在您运行该命令的目录中进行递归搜索工作流/ lfs / lfs_administration而且lfs / lfs_administration并将打印该文件和提到该文件的行。你可能会问为什么是两个grep。由于我们使用相对路径链接到文档，因此有时更深入地搜索路径可能会有用。
    • 的*。海事当文档链接到GitLab的内置帮助页面时，extension是不使用的，这就是为什么我们省略它git grep．
    • 使用MR文档描述模板上的核对表。

    重定向带有Disqus注释的页面

    如果要重新定位的文档页已经有任何Disqus注释，则需要保留Disqus线程。

    Disqus为每个页面使用一个标识符，对于docs.gitlab.com，页面标识符被配置为页面URL。因此，当我们更改文档位置时，我们需要保留旧的URL作为相同的Disqus标识符。

    为此，在frontmatter中添加变量redirect_from，使用旧的URL作为值。例如，假设我将文档移动到下面https://docs.gitlab.com/my-old-location/README.html去一个新的地方，https://docs.gitlab.com/my-new-location/index.html．

    到新文档首页添加以下内容:

    ---redirect_from：＇https://docs.gitlab.com/my-old-location/README.html的---

    注意:必须在文件中包含文件名redirect_fromURL，即使它是index . html或README.html．

    测试

    我们将文档视为代码，因此已经实现了一些测试。目前，进行了以下测试:

    1. 文档线头:检查所有内部(相对)链接是否正常工作，API文档中的所有cURL示例是否使用了完整的开关。建议你检查本地然后通过执行命令推到GitLab捆绑exec nanoc检查internal_links在你的本地gitlab-docs目录中。
    2. ee_compat_check(仅在CE上运行):当您向GitLab Community Edition (CE)提交合并请求时，会有这个附加的作业针对企业版(EE)运行，并检查您的更改是否可以清晰地应用到EE代码库。如果该作业失败，请阅读作业日志中的说明，了解下一步该做什么。由于CE每天合并到EE一次，因此避免合并冲突非常重要。提交一个等价于EE的合并请求——从CE选择所有提交到EE是避免它们的关键。

    分支命名

    如果你的捐献包含只有文档更改时，您可以通过遵循一些分支命名约定来加快CI过程。你有三个选择:

    分支机构名称 有效的例子
    从文档/ 文档/ update-api-issues
    从文档- docs-update-api-issues
    结束在文档 123 -更新- api -问题-文档

    如果分支名称与上述任何一个匹配，它将只运行文档测试。如果没有，整个测试套件将运行(包括文档)。

    合并GitLab文档的请求

    在开始之前，确保你阅读了介绍部分。为文档做贡献“在上面和上面技术写作工作流为GitLab团队成员。

    注意:注意:如果要向其中添加文档的发布版本已经被冻结或发布，请使用标签进入X.Y把它合并到正确的版本中。尽可能避免选择过去的版本，因为这会增加发布管理人员的工作。

    从CE挑选到EE

    因为我们有主如果每天有一次CE分支合并到EE中，那么遇到合并冲突是很常见的。为了避免他们，我们测试与EE的合并冲突与ee-compat-check作业，并使用以下方法为CE和EE创建等效的分支。

    遵循这个从CE到EE的选择方法，进行了一些调整:

    • 创建CE分支从文档-,例如:Git checkout -b docs-example
    • 创建以结尾的ee等效分支ee,例如,Git checkout -b docs-example-ee
    • 一旦所有的工作都传递给CE和EE，并且您已经处理了来自您自己团队的反馈，请将CE MR分配给技术作者进行审查
    • 当两个MRs都准备好时，EE合并请求将首先合并，然后合并ce等价请求。
    • 请注意，审查只会发生在CE MR中，因为EE MR包含与CE MR相同的提交。
    • 如果您有更多的仅应用于EE版本的更改，您可以向EE分支提交更多的提交，但是请审查人员另外向CE MR审查EE合并请求。如果有许多仅适用于EE的更改，则启动一个新的仅适用于EE的MR。

    实时预览更改

    若要在本地预览对文档的更改，请按此操作开发指南．

    如果你想实时预览合并请求的文档更改，你可以使用手册review-docs-deploy作业。您将至少需要主权限才能运行它，目前已为以下项目启用:

    注意:注意:你需要将一个分支推送到那些存储库中，这对fork不起作用。

    提示:提示:如果您的分支只包含文档更改，您可以使用特殊分支名称避免长时间运行管道。

    在迷你管道图中，您应该看到>>图标。点击它会显示review-docs-deploy的工作。点击播放按钮开始作业。

    手动触发文档构建＂class=

    这项工作将:

    1. 类中创建一个新分支gitlab-docs以方案命名的项目:预览——< branch-slug >
    2. 触发一个跨项目管道，用您的更改构建文档站点

    几分钟后，Review App将被部署，您将能够预览更改。docs的URL可以在两个地方找到:

    • 在合并请求小部件中
    • 的输出中review-docs-deploy作业，其中还包括触发的管道，以便您可以调查是否出现了问题

    如果Review App URL返回404，请按照以下步骤进行调试:

    1. 您是否遵循了来自合并请求小部件的URL ?如果是，请检查该链路是否与作业输出中的链路相同。如果分支名称slug长于35个字符，它可能会被自动截断。这意味着合并请求小部件将无法显示正确的URL，这是由于如何显示的限制环境:url方法的输出中找到真正的URLreview-docs-deploy的工作。
    2. 您是否遵循了作业输出中的URL ?如果是，则意味着站点还没有部署，或者远程管道出了问题。稍等几分钟，它就应该出现在线状态，否则，您可以从作业输出中的链接检查远程管道的状态。如果管道失败或被卡住，在管道中插入一根线#文档聊天频道。

    提示:提示:对CE/EE项目没有合并权限的人(想想贡献者的分支)将无法运行手动作业。在这种情况下，您可以请求GitLab团队中有权限为您做这件事的人。

    注意:注意:确保始终删除正在处理的合并请求的分支。如果你不这样做，远程文档分支也不会被删除，而托管评论应用程序的服务器最终将耗尽磁盘空间。

    技术方面

    如果你想知道热门细节，下面是真正发生的事情:

    1. 手动运行review-docs-deploy作业中的CE/EE合并请求。
    2. 该作业运行脚本/ trigger-build-docs脚本使用部署标志，这反过来:
      1. 获取分支名称并应用以下代码:
        • 分支名称的段塞是用来避免特殊字符的，因为最终NGINX将使用它。
        • 的预览,如果存在与您在合并请求中创建的名称相同的远程分支，则添加Prefix以避免冲突。
        • 最终的分支名称被截断为42个字符，以避免长分支名称(> 63个字符)的文件系统限制。
      2. 如果远程分支不存在，则创建远程分支(这意味着您可以根据需要多次重新运行手动作业，此步骤将被跳过)。
      3. 在docs项目中触发一个新的跨项目管道。
      4. 预览URL同时显示在作业输出和合并请求小部件中。您还可以获得到远程管道的链接。
    3. 在docs项目中，管道被创建跳过测试作业降低构建时间。
    4. 一旦构建了文档站点，HTML文件就会作为工件上传。
    5. 一个特定的Runner只绑定到文档项目，运行下载工件并使用的Review App作业rsync将文件传输到NGINX提供它们的位置。

    以下是GitLab的特性:

    GitLab/帮助

    每个GitLab实例都包含文档，可以从/帮助（http://my-instance.com/help),例如,https://gitlab.com/help．

    在构建新特性时，可能需要链接应用程序GitLab中的文档。的文件中通常完成此操作app / views /的帮助下的目录help_page_path辅助方法。

    以其最简单的形式，HAML代码生成一个链接到/帮助页面:

    ＝link_to“帮助页面”，help_page_path（“用户/权限”）

    的help_page_path包含要链接到的文档的路径，遵循以下约定:

    • 它是相对的文档/目录在GitLab存储库
    • 的。海事必须省略扩展名
    • 不能以斜杠(/）

    下面是一些应该根据上下文使用的特殊情况。您可以结合以下一个或多个:

    1. 链接到一个锚链接。使用锚作为help_page_path方法:

      ＝link_to“帮助页面”，help_page_path（“用户/权限”，主播:锚链接的）

    2. 在新选项卡中打开链接。这应该是默认的行为:

      ＝link_to“帮助页面”，help_page_path（“用户/权限”)，目标:“平等”

    3. 链接到一个圆图标。通常用于不能使用长描述的设置，比如复选框附近。你基本上可以使用任何字体的酷炫图标，但更喜欢question-circle：

      ＝link_to图标（“question-circle”)，help_page_path（“用户/权限”）

    4. 使用按钮链接。在文本与其余页面布局脱离上下文的地方很有用:

      ＝link_to“帮助页面”，help_page_path（“用户/权限”)，类:“btn btn-info”

    5. 使用一些文本的内联链接。

      描述# {link_to“帮助页面”，help_page_path（“用户/权限”）｝．

    6. 在句尾加句号。当你不想让句点成为链接的一部分时很有用:

      ＝成功“。”做欲知详情，请浏览＝link_to“帮助页面”，help_page_path（“用户/权限”）

    通用文档与技术文档

    一般的文档

    一般文档按用户，管理,贡献者，并描述该功能是什么，它可以做什么，以及它的可用设置。

    技术文章

    技术文章取代了曾经存在于网络中的技术内容GitLab博客在美国，它们已经过时，不容易被找到。

    它们是与主题相关的文档，使用用户友好的方法和语言编写，旨在为社区提供实现某些目标的具体过程的指导。

    技术文章指导用户和/或管理员实现某些目标(在指南和教程中)，或提供特定主题或特性的概述(在技术概述中)。它还可以描述第三方工具与GitLab的使用、实现或集成。

    它们应该放在一个名为文章标题/ index.md在一个主题相关的文件夹下，他们的图像应该放在/标题/ img /．例如，应该在GitLab Pages上放置一篇新文章doc / user /项目/页面/标题/应该在里面放一篇关于GitLab CI/CD的文章/标题/ doc / ci /例子．

    技术物品种类

    • 用户指南:技术内容，引导普通用户从A点到达B点
    • 管理指南:指导GitLab实例管理员从A点到B点的技术内容
    • 技术概述:描述特性、解决方案和第三方集成的技术内容
    • 教程:一步一步地提供如何做事或如何达到非常具体的目标的技术内容

    理解指南、教程和技术概述

    假设从a点到B点需要5个步骤:1 > 2 > 3 > 4 > 5．

    一个指南可以理解为对实现特定目标的特定过程的描述。指南将带您从A点到B点，描述该过程的特征，但不一定会详细介绍每个步骤。例如，它可以提到步骤2和步骤3，但不一定解释如何完成它们。

    一个教程需要明确循序渐进的实现单一目标的指导。它把你从A点带到B点，精确地描述了这个过程中涉及的所有必要步骤，展示了从A点到B点的5个步骤中的每一个步骤。它不仅描述了步骤2和步骤3，而且还告诉你如何完成它们。

    一个技术概述描述了某个特性是什么，它能做什么，但没有详细介绍如何系统地使用它。

    特殊格式

    每一个技术文章在文档的开头包含一个具有以下信息的正面内容:

    • 物品类型(用户指南、管理指南、技术概述、教程)
    • 知识水平期望读者能够坚持到底(初级，中级，高级)
    • 作者的名字而且GitLab.com处理
    • 出版日期(ISO格式YYYY-MM-DD)

    例如:

    ---作者：John Doeauthor_gitlab：johnDoe水平：初学者article_type：用户指南日期：2017-02-01---

    技术文章-写作方法

    使用写作方法由技术写作团队定义。

    Baidu
    map