本地开发指南

1. 你在这里:
2. Handbook 编写指南
3. 本地开发指南

维护者:

Xudong Guo

@guoxudong

• Gitpod.io
  • 快速开始
    • 开启 Gitpod 集成
    • 创建 Workspaces
    • 启用 Workspaces
    • 访问 Handbook 页面
  • 编辑 Handbook
  • 提交更改
  • 技术说明
• 本地开发
  • 环境准备
  • 运行 Middleman
  • Troubleshooting

Gitpod.io

Gitpod.io 是一个 "在云上建立的开发环境" 的第三方服务，在本地资源紧张或不可用时，其可以作为建立开发环境的替代方案。

您可以创建一个免费帐户，目前每月最多可以使用 50 小时。

其配置文件 /gitpod.yml 已经事先存放在项目中，完成配置后可直接使用。

快速开始

完成以下配置，就可以开始使用 Gitpod 了。

开启 Gitpod 集成

登录 GitLab，打开 https://jihulab.com/-/profile/preferences 页面，在 Integrations 一栏勾选 Enable Gitpod integration，然后点击保存。

之后就可以在 Project 页面看到 Gitpod 按钮了：

创建 Workspaces

Gitpod 有很好的文档。创建帐户后，可以通过以下方式创建 Workspaces：

• 在 GitLab 项目页面点击 Gitpod，该按钮与 Web IDE 共享一个按钮位置。
• 浏览器拓展：如果你安装了 Gitpod 浏览器拓展, 你会自动在 GitLab UI 中获得一个按钮来启动 Workspace（目前只支持 gitlab.com）。
• 使用 URLs:：除了浏览器拓展以外，最简单的方式就是直接在项目 URL 前添加 gitpod.io/#，例如 gitpod.io/#https://jihulab.com/gitlab-cn/handbook。

启用 Workspaces

Gitpod 会基于用户选择的分支在云端拉起一套开发环境，在开始前先创建好开发分支，推荐在相应 Issue 中点击 Create merge request 来创建开发分支。

第一次启动一个新的 Workspaces 需要一段时间来拉取 docker 镜像，下载并安装依赖，完成后会在浏览器打开一个 VS Code 页面，这时就完成了开发环境的创建。

访问 Handbook 页面

Workspaces 启动后会在终端开启三个 tab 页：

1. Handbook 页面（端口4567）
2. Marketing 页面（端口 4568）
3. web 站点说明页

前两个 “site server” 选项卡将自动安装依赖项并将 site server 作为后台守护进程启动。

第三个 “Instructions to view sites” 选项卡将自动更新以显示服务器启动的进度。全部完成后，您将看到消息：“The handbook and uncategorized sites are now available!”。

需要注意的是，经过测试，4567 端口的页面并不能正常限制，gitpod 将自动映射一个其他端口 7645 来展示 handbook，经过调试目前可以自动更新的页面效果，点击左侧 Remote Explorer 并点击 preview 按钮即可预览。

有时 Handbook 也有启动失败的情况，可以重新启动一个 handbook 的 site server 进程，方法如下：

1. 打开 Handbook site server (port 4567) tab 页，输入命令：

    ENABLE_LIVERELOAD=1 NO_CONTRACTS=true bundle exec middleman
   

2. 在弹出的选项卡中选择 make public，并记住该端口
3. 点击左侧选项卡小电视图标（Remote Explorer），选择刚刚打开的端口，地球图标是打开新页面，分隔框图标是在窗口内打开预览页面

编辑 Handbook

这是就可以在 sites/handbook/source/handbook 路径中修改 Handbook 内容了，修改完成后，使用 command+S 保存，之后刷新预览页就可以看到更改的内容了。

提交更改

这里的 push 操作与 VS Code 中类似，可在终端或者 UI 上进行该操作，这里不做过多介绍。

技术说明

• gitpod 与 CI/CD pipeline 中使用相同 docker 镜像
• 可以通过 pre-loaded 和 pre-installed 依赖项的 docker 镜像来优化启动速度

本地开发

直接在将 about-gitlab-cn 拉取到本地进行开发与调试。

环境准备

1. Handbook 使用 about-gitlab-cn repo 的 Ruby 版本进行设置的唯一可信源，所有依赖项都保存在该 repo 中。
2. 如果您使用的是 macOS，请安装 Homebrew，它是 macOS 的软件包管理器，可让您通过终端轻松安装程序和工具。
3. 按照 官方说明安装 nvm，nvm 是一个 Node 版本管理器。然后，在 about-gitlab-cn 目录中运行以下命令安装和使用存储库的 Node 版本：

     nvm install
     nvm use
   

   应该从 .nvmrc 文件中自动检测到所需的 Node 版本，可以使用 nvm which 来确认。

4. 安装 Yarn，一个 Node 生态系统的包管理器。

运行 Middleman

使用一下命令来安装依赖并启动开发模式的 Middleman：

bundle install
yarn

cd sites/XXX # NOTE: where XXX is one of the sites in the monorepo. For example: `cd sites/handbook` or `cd sites/uncategorized`

NO_CONTRACTS=true bundle exec middleman

如果您在本地开发中遇到任何问题，运行带有额外详细标志的命令可能会有所帮助。

NO_CONTRACTS=true bundle exec middleman --verbose

Middleman 运行成功后，就可以在浏览器中打开 http://localhost:4567/ 来查看实时的本地预览，source 目录中的任何更改都会被自动检测并重新加载页面。

PDF 文件在开发模式下不可用。请参阅下面的详细信息。

有关更多信息，请参考 Middleman 文档。

Troubleshooting

• 安装 ruby 2.7.2 失败
  报错: OpenSSL 1.1.1q failing to build… 原因: openssl bug
  解决方案:

  OPENSSL_CFLAGS=-Wno-error=implicit-function-declaration asdf install ruby
  

• 安装 eventmachine 失败 报错:

  ERROR: Failed to build gem native extension. 
  ...
  make failed, exit code 2
  

  原因: openssl 版本原因, 解决方案：指定版本安装

  gem install eventmachine -- --with-openssl-dir=/usr/local/opt/openssl@1.1
  

• 安装 libv8-node 失败 原因: Apple 移除了自带的python 需要手动安装python，并且能成功编译这个gem的只会有 2.7到3.9版本 解决:

  # 安装python 插件
  asdf plugin add python
  # 安装python
  asdf install python 3.9.16
  # 指定为默认版本
  asdf global python 3.9.16
  # 安装 gem
  gem install libv8-node -v '15.14.0.1'
  

此外，使用 asdf 安装 nodejs 12.4.0 也会因为python 问题而报错，使用 nvm 安装 nodejs 则可以绕过