为我们的文档做贡献
本网站文档托管在公共 GitHub 仓库中。它使用 Next.js 构建,使用 MDX 编写,并部署在 Vercel 上。
我们的文档理念
我们的文档旨在做到
- 高效:我们不想浪费任何人的时间
- 易于访问:阅读这里的文本不应要求母语为英语或拥有计算机科学学位
- 全面:文档网站应包含任何人使用 Meilisearch 所需的所有信息
- 开源:这是一个由 Meilisearch 用户为 Meilisearch 用户提供的资源
文档仓库和本地开发
Meilisearch 文档仓库仅存储文档网站的内容。由于构成网站的代码位于另一个仓库中,因此无法运行文档的本地副本。
处理图像和其他静态资源
当为 Meilisearch 文档贡献内容时,请将屏幕截图、图像、GIF 和视频存储在 /assets
下的相关目录中。
构建过程目前不支持带有相对路径的静态资源。将它们添加到文档时,请确保资源 URL 指向原始 GitHub 文件地址
\!\[Image description\]\(https://raw.githubusercontent.com/meilisearch/documentation/[branch_name]/assets/images/[guide_name]/diagram.png\)
如何贡献?
问题
Meilisearch 文档的维护者使用 GitHub Issues 来跟踪任务。有用的问题包括
- 通知文档团队内容不准确、过时或令人困惑
- 请求新功能,例如版本控制或嵌入式控制台
- 请求新内容,例如新指南和教程
在打开 issue 或 PR 之前,请查看我们的 未解决问题,看看是否已经存在针对您的问题的 issue。如果是,请留言告诉我们您正在等待修复或愿意自己解决。如果否,请打开一个新的 issue,描述问题并告知我们您是否想解决它。
我们热爱 Meilisearch 的 issue,因为它们帮助我们更好地完成工作。在十分之九的情况下,最有用的贡献是一个简单的 GitHub issue,它指出了问题并提出了解决方案。
创建您的第一个 issue
要打开 issue,您需要一个 GitHub 帐户。如有必要,创建一个,然后按照以下步骤操作
- 登录您的帐户
- 请访问 Meilisearch 文档仓库
- 点击 “Issues”(问题)
- 使用搜索栏查看是否有人报告了相同的问题。如果有人报告了,请点赞 👍,不要创建新 issue!
- 如果没有人报告您遇到的问题,请点击 “New issue”(新建 issue)
- 写一个简短且描述性的标题,然后添加更长的摘要来解释问题。如果您报告的是 bug,请务必包含重现错误的步骤,以及您的操作系统和浏览器版本
- 点击 “Submit new issue”(提交新 issue)
- 我们团队的成员应该很快 回复您
- 享受圆满完成工作的成就感!🎉
Pull requests(拉取请求)
您还可以通过提交 pull request 来改进文档。
Pull request(简称 “PR”)是请求将更改集成到 GitHub 仓库中的请求。在我们的文档上创建 PR 最简单的方法是使用每个页面左下角的 “Edit this page”(编辑此页)链接。
当您想要执行以下操作时,Pull request 特别有用:
- 解决 现有 issue
- 修复小错误,例如拼写错误或无效链接
- 创建或改进您非常了解的内容——例如,关于如何将 Meilisearch 与您掌握的工具集成的指南
在大多数情况下,最好在创建 PR 之前 创建 issue。这使您可以与文档维护者协调,并找到解决您想要解决问题的最佳方法。
创建您的第一个 PR
要创建 PR,您需要一个 GitHub 帐户。如有必要,请创建一个,然后按照以下步骤操作
- 转到您要编辑的文档页面,向下滚动,然后点击屏幕左下角的 “Edit this page”(编辑此页)。这将带您进入 GitHub
- 如果您尚未登录,请立即登录。系统可能会提示您创建 fork
- 使用 GitHub 的文本编辑器更新页面
- 向下滚动直到看到名为 “Propose changes”(提议更改)的框
- 在第一个字段中填写内容,为您的 PR 提供一个简短且描述性的标题——例如,“修复搜索 API 参考中的拼写错误”
- 使用第二个字段添加对您提议的更改的更详细的解释
- 点击 “Propose changes”(提议更改)按钮继续。您应该会看到一个显示 “Comparing changes”(比较更改)的页面
- 确保基本仓库设置为
meilisearch/documentation
,基本分支设置为main
。您可以忽略其余字段 - 此屏幕还将向您显示 “diff”,您可以通过它查看您所做的更改与当前发布在文档网站上的内容之间的比较
- 点击 “Create pull request”(创建 pull request)
- 恭喜,您已创建了第一个 PR! 文档维护者将很快审核您的 pull request。他们可能会要求进行更改,因此请密切关注您的 GitHub 通知
- 如果一切看起来都不错,您的工作将被合并到
main
分支中,并成为官方文档网站的一部分。您现在是 Meilisearch 贡献者了!🚀
我们如何审核贡献
我们如何审核 issue
在审核 issue 时,我们会考虑以下几个标准:
- 此任务是否是文档维护者的优先事项?
- 文档网站是否是此信息的最佳位置?有时,一个想法可能在我们的博客上比在文档中效果更好,或者链接到外部资源可能比我们自己编写和维护更有效
- 如果是 bug 报告,我们能否重现错误?
如果用户通过点赞或报告类似问题来表达对某个 issue 的兴趣,则文档更有可能投入资源来完成该任务。
我们如何审核 PR
对于审核贡献者 PR,我们首先确保 PR 符合我们的质量标准。
我们提出以下问题:
- 信息是否准确?
- 是否易于理解?
- 代码示例是否在没有错误的情况下运行?它们是否帮助用户理解我们正在解释的内容?
- 英文是否清晰简洁?非母语人士是否可以理解?
- 语法是否完美?是否有任何拼写错误?
- 我们是否可以在不丢失任何重要信息的情况下缩短文本?
- 建议的更改是否需要更新文档网站中的其他页面?
- 如果是新内容,文章是否放在正确的位置?文档中的其他文章是否应该链接到它?
没有什么比经过深思熟虑且有帮助的 PR 更让我们高兴的了。您的 PR 通常可以节省我们的时间和精力,并且它们使文档更加强大。
我们对 PR 贡献的唯一主要要求是作者在合理的时间范围内回复沟通请求。
一旦您在此仓库中打开 PR,我们团队的成员将很快前来审核。如果您的 PR 获得批准,则无需您执行任何其他操作。但是,如果在七天内您没有回复进一步更改或更多信息的请求,我们将认为 PR 已被放弃并将其关闭。
如果这种情况发生在您身上,并且您认为有误,请告知我们,我们将尽力纠正这种情况。
为 Meilisearch 做贡献
还有许多直接为 Meilisearch 做贡献的方式,例如:
还有许多有价值的方式来支持上述仓库:
- 提供反馈
- 建议功能
- 创建测试
- 修复 bug
- 添加内容
- 开发功能