-
Notifications
You must be signed in to change notification settings - Fork 14
如何在BakaXL QA Docs仓库提交您的更改
在 BakaXL-QA-docs 这个仓库中,我们关闭了直接提交功能,因此哪怕是这个仓库的创建者,以及作为第一批编写者也不能直接去提交修改到这个仓库的main
分支,都需要经过 Pull Request 确认无误后才能够进行推送
通常情况下,为了保证内容不会出错,并且避免过于频繁的修改,我们都是通过先 Fork(复刻) 这个仓库,而后你自己的个人账户下会有这个仓库,在你自己的仓库中修改好main
分支中你要更改的内容再通过 Pull request(拉取请求) 向我们的主仓库请求更新你的内容,当然,这些内容也会受到审查是否适宜为大众接受
你还需要学习基础的 Markdown 语法,这些教学内容你可以在 Runoob中找到
当然你也可以在 Runoob 学习 Git >>Runoob - Git教学
我们也会在这里教你一些基础的语法
在你 Fork 了我们的仓库后,你的个人账户下将会有一份与我们一样的仓库,但是他偶尔可能会过时,如果你点开仓库目录上方的Fetch upstream
时发现Fetch and merge
按钮是高亮的则代表我们的仓库进行了更新但是你的没有,你只需要按下这个按钮即可合并我们的更新
Markdown 和普通的 Office 文档差不多,只不过他不需要通过那些可视化按钮来操作文本的格式,而是通过自带的字符来标记这些内容为什么格式,当然也有可视化的 Markdown 编辑器,你可以去网络中搜索相关资源,接下来我们进行一些比较基础的 Markdown 语法教学
**文本** 可以加粗文本,效果: 文本
*文本* 可以让文本变成斜体,效果: 文本
# 标题 即为设置标题,效果 # 标题 【噢不,他显示不出来哈哈】 一个#代表一级标题,两个##(也就是##)代表二级标题,以此类推,我们最多可以使用六级标题
 可以设置图片,![]中的内容可以忽略不写,但是中括号一定要有,图片链接在我们的文档中只能是相对路径,在一般情况下是可以填入在线的链接
[文本](链接) 这样即可插入一个链接,文本和链接都需要有才会生效,可以是相对链接下的文档,也可以是一个网页什么的,效果: 百度
- 无序列表 在下方的注意事项中使用的便是无序列表注意在-和文字之间是有一个空格的
\1. 有序列表 有序列表的效果如下: 他和一般的列表没有区别,你甚至可以不用按照语法使用,因为有序列表本来就是这样,但是如果按照语法使用将来列表的样式有变更它也会跟着变更
- 第一份
- 第二份
- 第三份
> 引用文字 我们现在所显示的效果就是引用文字的效果,一般都是提示或注释用,在>和引用文字之间是有一个空格的,效果
引用文字
`代码` 一般的代码格式是用于标记命令等,但是我们不但要用于标记命令,还需要用于标记会遇到的Java错误,系统路径等,效果:
java.exception
代码标记的进阶用法是代码块通常是这样使用的:
```
代码内容
``` 其效果如下
代码内容
当你觉得你的文档编写的差不多了的时候你可以通过发起 Pull request 来让我们接受你编辑后的文档,按照以下步骤
- 打开 BakaXL 用户文档仓库的拉取请求页面
- 点击右上角绿色
New pull request
按钮 - 点击上方
compare across forks
超链接 - 你应看到与上方一样的界面,而后在
head epository
下拉框中选择以你的用户名为前缀的BakaXL-QA-docs
选项,大致长这样:XiaoMouz/BakaXL-QA-docs
,XiaoMouz是我的用户名 - 然后你应该可以看到右侧的
Create pull request
按钮变成了可点状态 - 在 Title 一栏中写上
来自xx(你的用户名)的更改——添加了xxx(添加的内容)
,在 Leave a comment 中写上你主要变动的文档以及解决的问题 - 点击下方的
Create pull request
按钮即可
以上便是关于文档的帮助内容以下是基本需要注意的注意事项
- 尽量避免叠加过多的 commits(提交次数),在检查文案后再提交你的更改至你自己的仓库是最好的
- 所有的文档都在仓库目录的
/docs
目录下 - 如果文档有相关的图片引用请务必以相对路径的方式引用(同时也就是说你必须将图片存在repo中而不是互联网)
- 如非必要请勿编辑
readme.md
根目录的和docs
目录的都不要更变,通常这些文档的更变都会经过交流群的协商
更多需要注意的在文档中的写作规范中,所有规范以写作规范文档为准
以下内容是为需要修改前端代码的人员准备的,如果您是文档修正人员无需理会以下内容
在修改这些代码前请确保你对vuepress
有所了解
你需要先将本仓库复刻至你自己的个人账户下,向你自己账户内的代码进行推送更改,在自行测试通过后即可向我们的仓库提交拉取请求至dev
分支
- 请在测试后代码能够构建的情况下发起拉取请求,将代码拉取至
dev
分支中,在dev
分支中确认能够正常构建至测试站后我们将会合并到main
分支 - 修改后的代码不得直接向到
main
分支提出拉取请求,所有向main
分支中提出拉取请求但是变更了/docs
目录外的内容的拉取请求均会被关闭 - 不得变更
.github/workflows/sync-website.yml
内的任何内容,如有需要请在群内协商后再做决定,所有对sync-website.yml
有更改的拉取请求均会被关闭 - 测试构建通过条件以您仓库的Github Actions记录为准
您需要在拉取请求的标题中写上您的主要修改内容,在拉取请求的附注中填写您具体修改/修复了什么问题 而后在附注中附上您复刻仓库的 Actions 链接,并且将 Actions 的 Log 截图(带上地址栏)以便确认构建情况
通常在您的复刻仓库中无论您如何更改内容都无法通过 Github Actions 的构建,我们在复刻仓库中确认构建通过的条件是日志通常最后两栏是
remote: Invalid username or password. fatal: Authentication failed for '***github.com/BakaXL-Support/BakaXL-docs-deploy.git/'
如果我们确认了 Log 最后两行为以上内容为这些则代表您的构建是通过的,只需检查修改内容是否能够受大众接受即可
您的修改需要能够受大众接受并且无害,在功能的增减方面上尽量只增不减
如果您的修改导致文档部分功能失效则您需要对这些失效部分进行维修,如果在dev
分支中您的推送表现不佳我们将会退回
如有疑问可以在
Discussions
或issues
中发出提问即可