README

COEM 包 .......................

Lorem ipsum 编写文档.

Logger

Lumen

迁移 日志表

  php artisan migrate --path=vendor/coem/package/src/migrations

激活 Logger 中间件

修改文件 bootstrap/app.php 并在 middleware 和 routeMiddleware 方法中添加以下行

	$app->middleware([
		...
		COEM\Middleware\LogMiddleware::class
	]);

	$app->routeMiddleware([
		...
		'log' => COEM\Middleware\LogMiddleware::class
	]);

Laravel

激活 Logger 中间件

修改文件 app/Http/Kernel.php 并在 middleware 和 routeMiddleware 变量中添加以下行

	protected $middleware = [
		...
		\COEM\Middleware\LogMiddleware::class
	];
 
	protected $routeMiddleware = [
		...
		'log' => \COEM\Middleware\LogMiddleware::class
	];

另见 编写文档.

文档的位置和命名

>注意： 这些指南源于在问题 #3349 中进行的讨论。

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

有了有结构的文档布局，我们将能够拥有有意义的URL，例如 docs.gitlab.com/user/project/merge_requests.html。使用这种模式，您可以立即知道您正在导航与用户相关的文档，并且它是关于项目和其合并请求的。

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

下表显示了哪些类型的文档属于哪里。

一般规则

1. 正确命名和定位新文档，是文档的相对URL和用于用户体验的GitLab Map设计的组合（来源，图片）。
2. 在创建新文档且其名称包含多个单词时，请确保使用下划线而不是空格或破折号（-）。例如，正确的命名方式为import_projects_from_github.md。同样的规则也适用于图片。
3. 有四个主要目录：user、administration、api和development。
4. doc/user/目录包含五个主要子目录：project/、group/、profile/、dashboard/和admin_area/。
   1. doc/user/project/应包含所有与项目相关的文档。
   2. doc/user/group/应包含所有与群组相关的文档。
   3. doc/user/profile/应包含所有与个人资料相关的文档。你将在/profile下导航的每个页面都应该有自己的文档，例如account.md、applications.md、emails.md等。
   4. doc/user/dashboard/应包含所有与仪表板相关的文档。
   5. doc/user/admin_area/应包含所有与行政相关的文档，描述了通过访问GitLab的行政界面可以实现的内容（不要与doc/administration混淆，后者需要服务器访问）。
      1. /admin/application_settings下的每个类别都应该在doc/user/admin_area/settings/下有自己的文档。例如，可见性和访问控制类别应该有一个文档位于doc/user/admin_area/settings/visibility_and_access_controls.md。
5. doc/topics/目录包含与主题相关的技术内容。当需要子主题时，创建doc/topics/topic-name/subtopic-name/index.md。一般用户和行政相关的文档应相应放置。
6. 对于技术文章，将它们的图片放在doc/articles/article-title/img/下。

如果你不确定文档应该放在哪里，可以在合并请求中ping @axil。

文本

• 拆分长行，这使审查和编辑变得更加容易。只有双行换行符在GitLab markdown中显示为完整的行断。
• 确保文档被添加到正确的目录中，并且有链接到它的一些有用的位置。
• 不要重复信息
• 简明扼要
• 除非有合理的理由不这样做，否则请按字母顺序添加文档
• 用美式英语书写
• 使用单空格而不是双空格

格式化

• 使用破折号（-）而不是星号（*）来表示无序列表
• 使用数字一（1）表示有序列表
• 使用下划线（_）来标记斜体字或文字
• 使用双星号（**）来标记粗体字或文字
• 在列表中使用时，最好不要在每个条目末尾使用句号。如果有多个句子，可以使用句号，但最后一个句子不要使用句号。

标题

• 每个文档中只添加一个H1标题，在标题开头添加#（当使用markdown时）。对于副标题，使用##、###等。
• 避免在标题中使用数字。数字会移动，因此文档锚点链接也会移动，最终导致死链接。如果你认为在标题中添加数字是必要的，请确保至少在合并请求中与某人讨论。
• 避免添加显示短暂状态的内容。例如，如果一个功能被认为是beta版或实验性的，请将此信息放在备注中，而不是标题中。
• 在引入新文档时，请注意标题的语法和句法正确性。建议提及以下GitLab成员之一或全部进行审阅：@axil、@rspeicher、@marcia。这是为了确保没有错误的标题的文档未经审核就上线，从而防止在修正时出现死链和重定向问题。
• 标题后应恰好留一个换行符。

链接

• 使用常规的行内链接Markdown标记[Text](https://example.com)。这样更容易阅读、审阅和维护。
• 如果同一文档中有多个重复的链接，可以使用[Text][identifier]，并在该部分或文档的底部添加：[identifier]: https://example.com。在这种情况下，我们鼓励您也添加一个替代文本：[identifier]: https://example.com "Alternative text"，当鼠标悬停在链接上时将显示此文本。

链接到行内文档

有时需要链接到GitLab在/help下提供的内置文档。这通常是通过在app/views/目录内的文件中，使用help_page_path辅助方法来完成的。

在最简单的情况下，生成/help页面链接的HAML代码是

= link_to 'Help page', help_page_path('user/permissions')

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

• 它是相对于GitLab仓库中的doc/目录的相对路径
• .md扩展名必须省略
• 它不能以斜杠（/）结束

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

1. 链接到锚点链接。将anchor作为help_page_path方法的一部分使用

   `haml = link_to '帮助页面', help_page_path('user/permissions', anchor: 'anchor-link') `

2. 在新标签页中打开链接。这应该是默认行为

   `haml = link_to '帮助页面', help_page_path('user/permissions'), target: '_blank' `

3. 链接到圆形图标。通常用于无法使用长描述的设置中，如复选框附近。您基本上可以使用任何font awesome图标，但首选question-circle

   `haml = link_to icon('question-circle'), help_page_path('user/permissions') `

4. 使用按钮链接。在文本与页面布局其余部分不相关的地方很有用

   `haml = link_to '帮助页面', help_page_path('user/permissions'), class: 'btn btn-info' `

5. 在文本中内联使用链接。

   `haml 描述为 #{link_to '帮助页面', help_page_path('user/permissions')}. `

6. 在句子的末尾添加句号。当您不希望句号成为链接的一部分时很有用

   `haml = succeed '.' do Learn more in the = link_to 'Help page', help_page_path('user/permissions') `

图片

• 将图片放在名为img/的单独目录中，该目录与您正在工作的.md文档位于同一目录。始终在它们的名字前加上它们将要包含的文档的名字。例如，如果有一个名为twitter.md的文档，那么一个有效的图片名字可以是twitter_login_screen.png。[**例外**：[文章](writing_documentation.md#technical-articles)的图片应该放在位于`/articles/article_title/img/`下的`img`目录中，因此不需要在文件名前添加文档名.]
• 图片应具有特定的、非通用的名字，以区分它们。
• 保持所有文件名都为小写。
• 考虑使用PNG图片而不是JPEG。
• 使用https://tinypng.com/或类似工具压缩所有图片。
• 使用https://ezgif.com/optimize或类似工具压缩GIF。
• 图片应该用来（仅在必要时）说明过程描述，而不是替代它。

文档内部

• 在文档中使用图片的Markdown方式是：![图片描述](img/document_image_title.png)
• 始终为图片提供一个适当的描述。这样，当浏览器无法显示图片时，此文本将用作替代描述
• 如果连续的图片之间有少量文字，请在图片和文字之间添加三个短横线（---），以创建水平线以获得更好的清晰度
• 如果标题直接跟在图片后面，请在图片和标题之间添加三个短横线（---）

注意事项

• 注意事项应使用粗体字注意：进行引用。使用以下格式

  >**注意：**这是需要注意的事项。

  它将渲染为

  >注意：这是需要注意的事项。

  如果注释跨越多行，可以在行之间拆分。

新功能

• 每个包含新功能的文档都应该声明该功能首次引入的GitLab版本。在标题下方添加注释

  > 在GitLab 8.3中引入。

• 如果可能，每个功能都应该有一个指向引入它的MR的链接。上面的注释将变为

  > [引入][ce-1242] 在GitLab 8.3中。

  ，其中链接标识符以存储库（CE）和MR编号命名。

• 如果该功能仅在GitLab企业版中提供，不要忘记提及，例如

  > 在GitLab企业版8.3中引入。

  否则，不要提及其他内容。

参考文献

• GitLab重启：有许多情况需要重启/重新配置GitLab。为了避免重复，请链接到可在doc/administration/restart_gitlab.md中找到的特别文档。通常文本将像这样阅读

  保存文件并[重新配置GitLab](../administration/restart_gitlab.md)，以使更改生效。如果您正在编辑的文档不在GitLab CE/EE doc/目录中，而不是相对链接，请使用完整路径：http://docs.gitlab.com/ce/administration/restart_gitlab.html。在适当的位置将reconfigure替换为restart。

安装指南

• Ruby：在安装指南的第2步中，我们从源安装Ruby。每当需要更新新版本时，请记住在代码块中更改它，并替换sha256sum（可以在Ruby网站的下载页面中找到）。

更改文档位置

更改文档的位置不应轻率进行。请记住，文档可供所有安装的help/目录下使用，而不仅限于GitLab.com或http://docs.gitlab.com。请确保在事先与文档团队讨论。

如果您确实需要更改文档的位置，请不要删除旧文档，而是用新行替换其全部内容

This document was moved to [another location](path/to/new_doc.md).

其中 path/to/new_doc.md 是到根目录 doc/ 的相对路径。

例如，如果您要将 doc/workflow/lfs/lfs_administration.md 移动到 doc/administration/lfs.md，则步骤如下

1. 将 doc/workflow/lfs/lfs_administration.md 复制到 doc/administration/lfs.md

2. 用以下内容替换 doc/workflow/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"

注意事项

• 由于我们使用内联文档，除了文档本身，文档还可能在GitLab的视图（app/）中被引用，当访问/help时渲染，有时也在测试套件（spec/）中。
• 上述git grep命令将在运行它的目录中递归搜索workflow/lfs/lfs_administration和lfs/lfs_administration，并将打印出提及此文件的文件和行。您可能会问为什么有两个grep。由于我们使用相对路径链接到文档，有时搜索更深的路径可能很有用。
• 当文档链接到GitLab的内置帮助页面时，不使用*.md扩展名，这就是为什么我们在git grep中省略它。

源和Omnibus安装的配置文档

GitLab目前官方支持两种安装方法：源安装和Omnibus包安装。

对于两种安装方法都可配置的设置，请优先在CE文档中记录，以避免重复。

配置设置包括

• 影响config/中配置文件的设置
• NGINX设置和一般lib/support/中的设置

当存在要执行的步骤列表时，通常涉及编辑配置文件并重新配置/重启GitLab。在这种情况下，以下风格作为指南

**For Omnibus installations**

1. Edit `/etc/gitlab/gitlab.rb`:

    ```ruby
    external_url "https://gitlab.example.com"
    ```

1. Save the file and [reconfigure] GitLab for the changes to take effect.

---

**For installations from source**

1. Edit `config/gitlab.yml`:

    ```yaml
    gitlab:
      host: "gitlab.example.com"
    ```

1. Save the file and [restart] GitLab for the changes to take effect.


[reconfigure]: path/to/administration/restart_gitlab.md#omnibus-gitlab-reconfigure
[restart]: path/to/administration/restart_gitlab.md#installations-from-source

在这种情况下

• 在每个步骤之前，用粗体声明安装方法
• 使用三个破折号（---）创建水平线，分隔两种方法
• 代码块缩进一个或多个空格，以便正确渲染
• 代码块中每个配置使用不同的高亮语言
• 使用参考资料指南重新配置/重启

伪造令牌

有时需要令牌来演示使用cURL的API调用或CI中使用的秘密变量。强烈建议不要在文档中使用真实令牌，即使被利用的概率很低。

以下伪造令牌可以作为示例。

API

以下是一份必需物品列表。请按照本文件中出现的顺序使用。以下给出进一步解释。

• 每种方法都必须有REST API请求。例如

  GET /projects/:id/repository/branches

• 每种方法都必须有参数的详细描述。

• 每种方法都必须有一个cURL示例。
• 每种方法都必须有一个响应体（JSON格式）。

方法描述

使用以下表头描述方法。属性应始终使用反引号（`）放在代码块中。

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |

渲染示例

cURL命令

• 使用https://gitlab.example.com/api/v4/作为端点。
• 在任何需要的地方使用此个人访问令牌： 9koXpg98eAheJpvBs5tK。
• 始终将请求放在第一位。默认情况下为 GET，因此无需包含它。
• 当URL包含附加参数时，请使用双引号。
• 建议使用个人访问令牌的示例，不要传递用户名和密码的数据。

cURL 示例

以下是一组您可以在API文档中使用的cURL示例。

简单的cURL命令

获取群组的详细信息

curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/gitlab-org

带有参数通过URL传递的cURL示例

在认证用户的命名空间下创建一个新的项目

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects?name=foo"

使用cURL的 --data 发送数据

您可以使用cURL的 --data 选项而不是使用 -X POST 并将参数附加到URI。下面的示例将在认证用户的命名空间下创建一个新的项目 foo。

curl --data "name=foo" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects"

使用JSON内容发送数据

注意：在此示例中，我们创建了一个新的组。请仔细观察单引号和双引号的使用。

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' https://gitlab.example.com/api/v4/groups

使用form-data发送数据

除了使用JSON或urlencode，您还可以使用multipart/form-data，它能够正确处理数据编码。

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." https://gitlab.example.com/api/v4/users/25/keys

上述示例由管理员运行，并将一个标题为ssh-key的SSH公钥添加到ID为25的用户账户中。

转义特殊字符

空格或斜杠（/）有时会导致错误，因此建议在可能的情况下转义它们。在下面的示例中，我们创建了一个包含标题中空格的新问题。观察空格是如何使用ASCII代码%20转义的。

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude"

使用%2F代表斜杠（/）。

将数组传递给API调用

GitLab API有时接受字符串或整数的数组。例如，要将GitLab实例的注册电子邮件域名限制为*.example.com和example.net，您将这样做

curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings