贡献者文档#

感谢您投入时间为项目做出贡献！您所做的任何贡献都将反映在最新版本的 Argilla 🤩 中。

请阅读行为准则，以保持社区的平易近人和互相尊重。

如果您是新的贡献者，我们建议您首先阅读新贡献者指南，如果不是这种情况，请随意跳转到您需要的部分。

新贡献者指南#

如果您是新的贡献者，请阅读 README 以了解项目概况。此外，这里有一些资源可以帮助您开始进行开源贡献

  • Discord：欢迎加入 Argilla Discord 社区，您可以在这里与其他用户、贡献者和 Argilla 团队保持联系。在下面的 章节 中，您可以找到有关如何在 Discord 中入门的更多信息。

  • Git：这是一个非常有用的工具，用于跟踪文件中的更改。使用命令行界面 (CLI)，您可以轻松地做出贡献。为此，您需要在计算机上安装并更新它。

  • GitHub：它是一个平台和基于云的服务，使用 git 并允许开发人员协作处理项目。要为 Argilla 做出贡献，您需要创建一个帐户。查看 使用 Git 和 Github 的贡献者工作流 以获取更多信息。

  • 开发者文档：要进行协作，您需要设置一个高效的环境。查看开发者文档以了解如何操作。

  • 与我们的开发者倡导者安排会议：如果您有更多问题，请随时联系我们的开发者倡导者并安排会议。

在 Discord 中首次联系#

Discord 是一个方便的工具，可以进行更随意的对话并回答日常问题。作为 Hugging Face 的一部分，我们在服务器上设置了一些 Argilla 频道。点击此处轻松加入 Hugging Face Discord 社区。

加入 Hugging Face Discord 后，您可以选择“频道和角色”，然后选择“Argilla”以及您感兴趣的任何其他群组。“Argilla”将涵盖有关 argilla 和 distilabel 的任何内容。您可以加入以下频道

  • #argilla-distilabel-general：📣 保持最新状态和一般性讨论。

  • #argilla-distilabel-help：🙋‍♀️ 需要帮助吗？我们随时为您提供帮助。为您的 issue 选择合适的标签（argilla 或 distilabel）并发布它。

所以现在只剩下一件事要做：介绍你自己并与社区交谈。你总是会受到欢迎！ 🤗👋

使用 Git 和 GitHub 的贡献者工作流#

如果您正在使用 Argilla，并且突然有一个新想法出现在您的脑海中，或者您发现了一个可以改进的问题，那么现在是积极参与并为项目做出贡献的时候了！主要步骤如下

  1. 报告 issue

  2. 使用 fork

  3. 创建新分支

  4. 进行更改并推送它们

  5. 创建拉取请求

  6. 审查您的拉取请求

  7. 您的 PR 已合并！

报告 issue#

如果您发现问题，请搜索是否已存在 issue。您可以使用 Label 过滤器。如果是这种情况，请参与对话。如果不存在，请单击 New Issue 创建一个 issue。

issues-page

这将显示各种模板，选择最适合您 issue 的模板。

templates-issues

下面，您可以看到 Feature request 模板的示例。选择一个后，您需要按照指南填写它。尽量尽可能清晰。此外，您可以将自己分配给该 issue 并添加或选择正确的标签。最后，单击 Submit new issue。

issue-feature-template

使用 fork#

Fork Argilla 仓库#

报告 issue 后，您可以开始处理它。为此，您需要创建项目的 fork。为此，请单击 Fork 按钮。

fork-bar

现在，填写信息。如果您要处理或从另一个分支工作（例如，为了修复文档，使用 main 分支），请记住取消选中 Copy develop branch only。然后，单击 Create fork。

create-fork

现在，您将被重定向到您的 fork。您可以看到您在您的 fork 中，因为仓库的名称将是您的 username/argilla，并且它将指示 forked from argilla-io/argilla。

克隆您 fork 的仓库#

为了进行必要的调整，请将 fork 的仓库克隆到您的本地计算机。选择目标文件夹并运行以下命令

git clone https://github.com/[your-github-username]/argilla.git
cd argilla

为了使您的 fork 的 main/develop 分支与我们的仓库保持同步，请将其添加为上游远程分支。有关更多信息，请查看文档。

git remote add upstream https://github.com/argilla-io/argilla.git

创建新分支#

对于您要处理的每个 issue，建议创建一个新分支。GitHub 提供了一种直接的方法来简化此过程。

⚠️ 永远不要直接在 main 或 develop 分支上工作。始终为您的更改创建一个新分支。

导航到您的 issue，然后在右侧列中，选择 Create a branch。

create-branch-issue

在新窗口弹出后，分支将以 issue 命名，包括前缀，例如 feature/、bug/ 或 docs/，以方便快速识别 issue 类型。在 Repository destination 中，选择您的 fork ([您的-github-用户名]/argilla)，然后选择 Change branch source 以指定创建新分支的源分支。单击 Create branch 完成此过程。

🤔 请记住，main 分支仅用于处理文档。对于任何其他更改，请使用 develop 分支。

create-branch

现在，在本地切换到您刚刚创建的新分支。

git fetch origin
git checkout [branch-name]

使用 CHANGELOG.md#

如果您正在开发新功能，最好记录下来，以便其他人跟上更改。为此，我们使用根目录中的 CHANGELOG.md 文件。此文件用于列出项目每个版本中所做的更改，并且我们使用标题来表示每种类型的更改。

  • Added: 用于新功能。

  • Changed: 用于现有功能的更改。

  • Deprecated: 用于即将删除的功能。

  • Removed: 用于现在删除的功能。

  • Fixed: 用于任何错误修复。

  • Security: 在出现漏洞的情况下。

一个示例添加将是

- Fixed the key errors for the `init` method ([#NUMBER_OF_PR](LINK_TO_PR)). Contributed by @github_handle.

您可以查看 CHANGELOG.md 文件以查看更多案例和示例。

进行更改并推送它们#

在本地仓库中进行您想要的更改，并测试一切正常，并且您遵循了指南。查看文档以获取有关开发的更多信息。

完成后，您可以检查仓库的状态，并通过以下命令与上游仓库同步

# Check the status of your repository
git status

# Synchronize with the upstreaming repo
git checkout [branch-name]
git rebase [default-branch]

如果一切正常，我们需要提交并将更改推送到您的 fork。为此，请运行以下命令

# Add the changes to the staging area
git add filename

# Commit the changes by writing a proper message
git commit -m "commit-message"

# Push the changes to your fork
git push origin [branch-name]

推送时，系统会要求您输入 GitHub 登录凭据。推送完成后，所有本地提交都将在您的 GitHub 仓库中。

创建拉取请求#

返回 GitHub，导航到您创建 fork 的原始仓库，然后单击 Compare & pull request。

compare-and-pr

首先，单击 compare across forks 并选择正确的仓库和分支。

在基础仓库中，请记住根据所做的修改选择 main 或 develop。在 head 仓库中，指示您 fork 的仓库和与 issue 对应的分支。

compare-across-forks

然后，填写拉取请求模板。在标题中，根据修改的类型添加 feat、bug 或 docs 前缀。将显示一个通用模板，请单击 Preview 并选择相应的拉取请求模板。此外，在右侧，您可以选择审阅者（例如，如果您与 Argilla 团队的成员讨论过该 issue）并将拉取请求分配给自己。

强烈建议也为 PR 添加标签。您可以通过屏幕右侧的标签部分再次执行此操作。例如，如果您正在解决 bug，请添加 bug 标签，或者如果 PR 与文档相关，请添加 documentation 标签。这样，可以轻松筛选 PR。

此外，您应该像上面对分支所做的那样，为 PR 名称添加前缀。如果您正在开发新功能，则可以将 PR 命名为 feat: TITLE。如果您的 PR 包含 bug 的解决方案，则可以将 PR 命名为 bug: TITLE。并且，如果您的工作是为了改进文档，则可以将 PR 命名为 docs: TITLE。

最后，单击 Create pull request。

pr

下面，我们选择了功能模板。现在，仔细填写它并遵循指南。请记住链接原始 issue。最后，启用复选框以允许维护者编辑，以便可以更新分支以进行合并，然后单击 Create pull request。

pr-feature-template

审查您的拉取请求#

提交 PR 后，团队成员将审查您的提案。我们可能会提出问题、索取更多信息或要求在合并 PR 之前进行更改，可以使用 建议的更改 或拉取请求评论。

您可以直接通过 UI 应用更改（检查已更改的文件并单击右上角的三点，请参见下图），或从您的 fork 应用更改，然后将它们提交到您的分支。PR 将自动更新，建议将显示为已过时。

edit-file-from-UI

如果您遇到任何合并问题，请查看此 git 教程，以帮助您解决合并冲突和其他问题。

您的 PR 已合并！#

恭喜 🎉🎊 我们感谢您 🤩

PR 合并后，您的贡献将在 Argilla GitHub 上公开可见。

此外，我们将根据我们的 开发分支 将您的更改包含在下一个版本中。

其他资源#

以下是一些有用的资源供您参考。