Skip to content

如何在BakaXL QA Docs仓库提交您的更改

XiaoMouz edited this page Apr 20, 2022 · 9 revisions

在文档上的更改

在 BakaXL-QA-docs 这个仓库中,我们关闭了直接提交功能,因此哪怕是这个仓库的创建者,以及作为第一批编写者也不能直接去提交修改到这个仓库的main分支,都需要经过 Pull Request 确认无误后才能够进行推送

如何修改文档

通常情况下,为了保证内容不会出错,并且避免过于频繁的修改,我们都是通过先 Fork(复刻) 这个仓库,而后你自己的个人账户下会有这个仓库,在你自己的仓库中修改好main分支中你要更改的内容再通过 Pull request(拉取请求) 向我们的主仓库请求更新你的内容,当然,这些内容也会受到审查是否适宜为大众接受

>>点击 Fork 此仓库

你还需要学习基础的 Markdown 语法,这些教学内容你可以在 Runoob中找到

当然你也可以在 Runoob 学习 Git >>Runoob - Git教学

我们也会在这里教你一些基础的语法

如何更新并同步我们的仓库

在你 Fork 了我们的仓库后,你的个人账户下将会有一份与我们一样的仓库,但是他偶尔可能会过时,如果你点开仓库目录上方的Fetch upstream时发现Fetch and merge按钮是高亮的则代表我们的仓库进行了更新但是你的没有,你只需要按下这个按钮即可合并我们的更新

Markdown

Markdown 和普通的 Office 文档差不多,只不过他不需要通过那些可视化按钮来操作文本的格式,而是通过自带的字符来标记这些内容为什么格式,当然也有可视化的 Markdown 编辑器,你可以去网络中搜索相关资源,接下来我们进行一些比较基础的 Markdown 语法教学

**文本** 可以加粗文本,效果: 文本

*文本* 可以让文本变成斜体,效果: 文本

# 标题 即为设置标题,效果 # 标题 【噢不,他显示不出来哈哈】 一个#代表一级标题,两个##(也就是##)代表二级标题,以此类推,我们最多可以使用六级标题

![文本](图片链接) 可以设置图片,![]中的内容可以忽略不写,但是中括号一定要有,图片链接在我们的文档中只能是相对路径,在一般情况下是可以填入在线的链接

[文本](链接) 这样即可插入一个链接,文本和链接都需要有才会生效,可以是相对链接下的文档,也可以是一个网页什么的,效果: 百度

- 无序列表 在下方的注意事项中使用的便是无序列表注意在-和文字之间是有一个空格的

\1. 有序列表 有序列表的效果如下: 他和一般的列表没有区别,你甚至可以不用按照语法使用,因为有序列表本来就是这样,但是如果按照语法使用将来列表的样式有变更它也会跟着变更

  1. 第一份
  2. 第二份
  3. 第三份

> 引用文字 我们现在所显示的效果就是引用文字的效果,一般都是提示或注释用,在>和引用文字之间是有一个空格的,效果

引用文字

`代码` 一般的代码格式是用于标记命令等,但是我们不但要用于标记命令,还需要用于标记会遇到的Java错误,系统路径等,效果: java.exception

代码标记的进阶用法是代码块通常是这样使用的:

```

代码内容

``` 其效果如下

代码内容

提交更改

当你觉得你的文档编写的差不多了的时候你可以通过发起 Pull request 来让我们接受你编辑后的文档,按照以下步骤

  1. 打开 BakaXL 用户文档仓库的拉取请求页面
  2. 点击右上角绿色New pull request按钮
  3. 点击上方compare across forks超链接
  4. 选择拉取远程库
  5. 你应看到与上方一样的界面,而后在head epository下拉框中选择以你的用户名为前缀的BakaXL-QA-docs选项,大致长这样:XiaoMouz/BakaXL-QA-docs,XiaoMouz是我的用户名
  6. 然后你应该可以看到右侧的Create pull request按钮变成了可点状态
  7. 在 Title 一栏中写上来自xx(你的用户名)的更改——添加了xxx(添加的内容),在 Leave a comment 中写上你主要变动的文档以及解决的问题
  8. 点击下方的Create pull request按钮即可

以上便是关于文档的帮助内容以下是基本需要注意的注意事项

注意事项

  • 尽量避免叠加过多的 commits(提交次数),在检查文案后再提交你的更改至你自己的仓库是最好的
  • 所有的文档都在仓库目录的/docs目录下
  • 如果文档有相关的图片引用请务必以相对路径的方式引用(同时也就是说你必须将图片存在repo中而不是互联网)
  • 如非必要请勿编辑readme.md根目录的和docs目录的都不要更变,通常这些文档的更变都会经过交流群的协商 SbmlJptZEF

更多需要注意的在文档中的写作规范中,所有规范以写作规范文档为准

修改前端代码

以下内容是为需要修改前端代码的人员准备的,如果您是文档修正人员无需理会以下内容

在修改这些代码前请确保你对vuepress有所了解 你需要先将本仓库复刻至你自己的个人账户下,向你自己账户内的代码进行推送更改,在自行测试通过后即可向我们的仓库提交拉取请求至dev分支

Pull request 要求

  • 请在测试后代码能够构建的情况下发起拉取请求,将代码拉取至dev分支中,在dev分支中确认能够正常构建至测试站后我们将会合并到main分支
  • 修改后的代码不得直接向到main分支提出拉取请求,所有向main分支中提出拉取请求但是变更了/docs目录外的内容的拉取请求均会被关闭
  • 不得变更.github/workflows/sync-website.yml内的任何内容,如有需要请在群内协商后再做决定,所有对sync-website.yml有更改的拉取请求均会被关闭
  • 测试构建通过条件以您仓库的Github Actions记录为准

Pull request 通过条件

您需要在拉取请求的标题中写上您的主要修改内容,在拉取请求的附注中填写您具体修改/修复了什么问题 而后在附注中附上您复刻仓库的 Actions 链接,并且将 Actions 的 Log 截图(带上地址栏)以便确认构建情况

通常在您的复刻仓库中无论您如何更改内容都无法通过 Github Actions 的构建,我们在复刻仓库中确认构建通过的条件是日志通常最后两栏是

remote: Invalid username or password.
fatal: Authentication failed for '***github.com/BakaXL-Support/BakaXL-docs-deploy.git/'

如果我们确认了 Log 最后两行为以上内容为这些则代表您的构建是通过的,只需检查修改内容是否能够受大众接受即可

您的修改需要能够受大众接受并且无害,在功能的增减方面上尽量只增不减 如果您的修改导致文档部分功能失效则您需要对这些失效部分进行维修,如果在dev分支中您的推送表现不佳我们将会退回

↑ 打开上方Pages能访问Wiki完整内容

快来和我们一起改进BakaXL帮助文档吧!

fork本仓库

Clone this wiki locally