贡献代码

4.0

4.0 2.3

在为 Masonite 做贡献时，请首先通过GitHub issue进行发布。在GitHub issue上，所有贡献者和维护者都有机会就这个问题发表意见。它创建了一个公共论坛，讨论实施问题、修复或改进的最佳方式。它还就是否允许该问题出现在项目中展开了公开讨论。

请注意，我们有行为准则，请在您与项目的所有互动中都遵循该准则。您可以在核心项目目录的底部找到它。

入门

该框架包含了两个主要部分：「核心」存储库和「Cookie-Cutter」存储库。

MasoniteFramework/cookie-cutter存储库是使用project start命令创建新项目时安装的主存储库。这实际上是一个完整的 Masonite 项目。当您运行project start时，它只会访问该GitHub存储库，获取 zip 并将其解压缩到您的计算机上。除非在默认安装中需要进行某些更改，否则不会在此存储库中进行太多开发，也不会对其进行更改。

MasoniteFramework/core存储库已弃用，开发已移至MasoniteFramework/masonite中。该存储库包含 Masonite 的所有开发，包含 Masonite 的所有版本。如果您需要修复错误或添加新功能，则可以使用这个库。

MasoniteFramework/craft已弃用。这是 CLI 工具库所在的位置，该工具库已移入masonite存储库。

启动并运行 Masonite cookie-cutter 存储库以进行编辑

你可以在此处了解框架的流程、工作原理和架构概念

这个 repo 很简单，可以按照 README 中的安装说明进行安装。

• fork MasoniteFramework/cookie-cutter 存储库。
• 将该 repo 克隆到你的计算机中：
  • git clone http://github.com/your-username/cookie-cutter.git
• 检查当前发布分支（例如：develop）
  • git checkout -b develop
• 你现在应该在 develop 本地分支上。
• 运行 git pull origin develop 以获取当前发布版本。
• 从那里只需创建你的功能分支 (<feature|fix>-<issue-number>) 并进行所需的更改。
• 推送到你的原始存储库：
  • git push origin change-default-orm
• 打开拉取请求并按照下面的 PR 流程进行操作

编辑 Masonite 存储库

这样做的诀窍是我们需要它被 pip 安装，然后快速编辑直到我们喜欢它，然后推回 repo 进行 PR。仅当您想要更改核心 Masonite 包时才执行此操作

为此，你只需：

• fork MasoniteFramework/masonite 存储库，
• 将该 repo 克隆到你的计算机中：
  • git clone http://github.com/your-username/masonite.git
• 激活你的 masonite 虚拟环境（可选）
  • 转到安装 masonite 的位置并激活环境
• 在虚拟环境中，cd 进入你安装 core 的目录。
• 从 masonite 目录中运行 pip install -e .。这将以可编辑模式将 masonite 安装为 pip 包。你对代码库所做的任何更改都将立即在你的项目中可用。你可能需要重新启动开发服务器。
• 你对此包所做的任何更改只需推送到 fork 上的功能分支并遵循以下 PR 流程。

注释

注释是任何存储库的重要组成部分，应在需要时使用。重要的是不要过度评论某事。如果你发现你需要不断地添加注释，那么你的代码可能太复杂了。代码应该是自我记录的（具有明确定义的变量和方法名称）

要使用的评论类型

在为 Masonite 开发时，你应该使用 3 种主要类型的注释：

模块声明

所有模块都应该在每个模块文件的顶部都有一个声明，并且应该看起来像：

"""这是一个添加对计费用户的支持的模块。"""
from masonite.request import Request
...

注意句子前后没有空格。

方法和函数声明

所有方法和函数还应包含一个声明，其中简要描述了模块的作用

例如：

def some_function(self):
    """这是一个执行 x 动作的函数。

    然后举例说明何时使用它
    """
    ... 具体的代码 ...

具有依赖关系的方法和函数

大多数方法都需要一些依赖项或参数。你必须像这样指定它们：

def route(self, route, output):
    """将路线加载到类中。这也寻找控制器并将其附加到路由。

    Arguments：
        route {string} -- 这是附加到路由 (/dashboard/user) 的 URI。
        output {string|object} -- 附加到路由的控制器。

    Returns:
        self
    """

如果你的依赖项是对象，它应该提供模块的路径：

def __init__(self, request: Request, csrf: Csrf, view: View):
    """初始化 CSRF 中间件

    Arguments:
        request {masonite.request.Request} -- 正常的 Masonite 请求类。
        csrf {masonite.auth.Csrf} -- CSRF 身份验证类。
        view {masonite.view.View} -- 正常的 Masonite 视图类。

    Returns:
        self
    """
    pass

代码注释

代码注释应该留到最低限度。如果你的代码复杂到需要注释的程度，那么你应该考虑重构代码而不是添加注释。如果你的代码必须足够复杂以至于未来的开发人员可能无法理解，请在其上方添加 # 注释。

对于普通代码，这将类似于：

# 此代码执行一个复杂的任务，以后可能无法理解
# 你可以像这样添加第二行
complex_code = 'value'

perform_some_complex_task()

Pull Request 流程

请仔细阅读此过程，以防止 Pull Request 被拒绝。

1. 你应该在提出任何拉取请求之前打开一个 Issue 。并非所有功能都将添加到框架中，有些功能作为第三方包可能会更好，或者根本不添加。如果你在一个功能上工作了几天，并且由于可能在一个问题中讨论了几分钟的原因而拉取请求被拒绝，那就不好了。
2. 确保所有更改都得到很好的注释，并且添加的任何配置文件都对其设置的变量具有文档字符串注释。请参阅上面的评论部分。
3. 涉及到 UI 或更改配置信息的，请更新 MasoniteFramework/docs 存储库（以及 MasoniteFramework/masonite 存储库中的 README.md（如果适用））。这包括新环境变量、新文件位置、容器参数、新功能说明等。
4. 以 <feature|fix>/<issue-number> 的形式命名你的分支。例如，如果你正在修复错误并且 Issue 编号是 576，那么将您的分支命名为 fix/576。这将有助于我们以后在我们的计算机上找到分支。如果它是一个新的功能名称，它是 feature/576。
5. 你必须为 PR 合并之前所做的任何更改添加单元测试。如果你不确定如何编写上面列出的存储库的单元测试，你可以打开拉取请求，我们会将测试添加进去。
6. 增加任何示例文件（如 setup.py）中的版本号以及此 Pull Request 将代表的新版本。我们使用的版本控制方案是 SEMVER。
7. PR 必须传递在拉取请求上运行的 GitHub Action。一旦你从其他两个合作者那里获得了成功的审核，或者从维护者那里获得了一次审核，你就可以合并拉取请求。

分支管理

分支管理也很重要。根据你所做的修复或功能，你将需要从其他分支合并回到当前分支。 Masonite 的简单分支：

1) 所有 Masonite 存储库、包等都遵循相同的基本分支流程。

2）每个存储库有：当前发布分支、先前发布分支、主分支和开发分支。

3) 当前版本分支是当前版本所在的分支。例如，Masonite 的版本为 2.3，因此当前发布分支将是 2.3。

4）以前的版本分支是一样的，但只是以前的版本。因此，如果 Masonite 当前在 4.0 上，那么之前的版本分支可能是 3.0、2.1、2.2 等。

5) master 分支是一个暂存分支，最终会合并到当前的发布分支中。这里是所有非破坏性更改将上演/出现的地方（新的非破坏性功能和错误修复）。

6) develop 分支是 到下一个主要版本 的暂存分支。例如，Masonite 将使用 4.0 版本。如果你对某个功能有想法，但它会破坏现有功能，那么你将从（并返回）分支到 develop 分支。该分支最终将合并到 4.1 分支，并在下一个主要版本发布时成为其一部分。

例子:

例如，如果你想创建一个新功能并且你知道它不会破坏任何东西（例如添加排队功能），那么你将按照上面的拉取请求流程从主分支分支。 PR 将对 master 分支开放。然后，此功能将合并到当前发布分支中，并作为新的次要版本凹凸 (4.1.0) 发布。

不破坏任何内容的错误修复与上述过程相同。

新功能将是相同的过程，但会从 develop 分支分支出来。你将进行更改，然后向 develop 分支打开拉取请求。这是一个长期运行的分支，将在 Masonite 的下一个主要版本准备好发布后合并。

行为守则

我们的承诺

为了营造一个开放和热情的环境，我们作为贡献者和维护者承诺，无论年龄、体型、残疾、种族、性别认同和表达方式如何，参与我们的项目和社区的每个人都不会受到骚扰，经验水平、国籍、个人外表、种族、宗教或性身份和性取向。

我们的标准

有助于创造积极环境的行为示例包括：

• 使用欢迎和包容的语言
• 尊重不同的观点和经历
• 优雅地接受建设性的批评
• 专注于对社区最有利的事情
• 对其他社区成员表示同情

参与者不可接受的行为示例包括：

• 使用性感的语言或图像以及不受欢迎的性关注或挑逗
• 拖钓、侮辱/贬损评论，以及人身或政治攻击
• 公共或私人骚扰
• 未经明确许可发布他人的私人信息，例如物理地址或电子地址
• 在专业环境中可能被合理认为不适当的其他行为

我们的责任

项目维护人员负责阐明可接受行为的标准，并期望针对任何不可接受行为的情况采取适当和公平的纠正措施。

项目维护者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、wiki 编辑、问题和其他贡献，或暂时或永久禁止任何贡献者的其他行为他们认为不适当、威胁、冒犯或有害。

适用范围

当个人代表项目或其社区时，本行为准则适用于项目空间和公共空间。代表项目或社区的示例包括使用官方项目电子邮件地址、通过官方社交媒体帐户发布信息或在在线或离线活动中担任指定代表。项目的表示可以由项目维护者进一步定义和澄清。

监督与执行

可以通过 joe@masoniteproject.com 联系项目团队来报告辱骂、骚扰或其他不可接受的行为。所有投诉都将被审查和调查，并将产生被认为必要且适合具体情况的回应。项目团队有义务对事件的报告者保密。具体执行政策的更多细节可能会单独发布。

不善意遵守或执行行为准则的项目维护者可能会面临由项目领导的其他成员确定的临时或永久影响。

准则参考来源

本行为准则改编自 贡献者契约 版本 1.4，可在 http://contributor-covenant.org/version/1/4 查阅

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/masonite/4.0/pr...

译文地址：https://learnku.com/docs/masonite/4.0/pr...