贡献指南

简介

在为 Masonite 做贡献时，请首先通过 GitHub 发布或在 Masonite Slack 频道中讨论您希望进行的更改。

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

入门

该框架包含三个主要部分：「核心」存储库，「Cookie-Cutter」存储库和常规 CLI 工具。

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

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

MasoniteFramework / craft已弃用。自那时起，手工 CLI 工具就在这里生活了，此工具已移至masonite存储库中。 Masonite 2.2 及更低版本仍然需要此存储库，因此，如果您需要对 Masonite 2.2 的内容进行更改，则可以在此存储库中进行。如果您需要在 Masonite 2.3 及更高版本中更改内容，请直接在core中进行。

启动并运行 Masonite Cookie-Cutter 仓库以进行编辑

您可以在此处了解框架的流程，工作原理和体系结构概念

此仓库很简单，可以按照自述文件中的安装说明进行安装。

• 分支库 MasoniteFramework/cookie-cutter.
• 将该仓库克隆到您的计算机中:
  • 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，然后才能对其进行快速编辑，然后再将其推回仓库以进行 PR。仅当您要更改核心 Masonite 软件包时才执行此操作

为此，只需：

• 分支库 MasoniteFramework/masonite,
• 将该仓库克隆到您的计算机中:
  • git clone http://github.com/your-username/masonite.git
• 激活您的 masonite 虚拟环境 (可选)
  • 转到安装 masonite 的位置并激活环境
• 在虚拟环境中, cd 进入您安装核心的目录.
• 在 masonite-core 目录中运行pip install。。这将安装 masonite 作为 pip 包。
• 您对该软件包所做的任何更改都只需将其推送到 fork 上的功能分支，并遵循以下 PR 流程即可。

此仓库有一个示例项目的基本框架，以便帮助根据实际项目测试 Masonite 的所有功能。如果安装时添加 --editable 标志将以可编辑方式安装，这可能会破坏你的项目，因为它将用你的应用程序模块覆盖此软件包中的模块。

编辑 craft 仓库 (craft 命令)

craft 命令构成了 Masonite 工作流程的很大一部分。请按照以下说明在你的计算机上获取 masonite-cli 包并对其进行编辑。

如果要更改的 Masonite 的 CLI 工具为2.3或更高版本，请在 MasoniteFramework/craft 仓库中进行更改。

• 派生 MasoniteFramework/craft 到自己的仓库
• 克隆该仓库到你的计算机上：
  • git clone http://github.com/your-username/craft.git
• 激活 masonite 虚拟环境 (可选)
  • 转到安装 masonite 的位置并激活环境
• 在虚拟环境中，切换到安装 cli 的目录
• 在 masonite-cli 目录运行 pip install --editable . 命令。这将以 pip 包的方式安装 craft (包含 craft 命令) ，但还会保留对文件夹的引用，因此你可以自由地对 craft 命令进行更改，而不必担心会不断地重新安装它。
• 对该软件包所做的任何更改都只需将其推送到你派生出的功能分支，并遵循以下 PR 流程即可。

注释

注释是任何仓库的重要组成部分，应在需要时使用。重要的是不要过分使用注释。如果发现需要不断添加注释，那么你的代码可能太复杂了。代码应该是自带文档的 (具有明确定义的变量和方法名称)

要使用的注释类型

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

模块文档字符串

所有模块在每个模块文件的顶部都应该有一个文档字符串，应该类似于下面的示例：

"""这是一个对 Billing 用户提供支持的模块。"""
from masonite.request import Request
...

注意注释语句前后没有空格。

方法和函数文档字符串

所有方法和函数也应该包含文档字符串，用于简要说明模块的功能

例如：

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

    然后举例说明何时使用它
    """
    ... code ...

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

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

def route(self, route, output):
    """将路由加载到类中，同时查找控制器并将其附加到路由。

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

    返回值：
        self
    """

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

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

    参数：
        request {masonite.request.Request} -- 一般的 Masonite 请求类。
        csrf {masonite.auth.Csrf} -- CSRF 身份验证类。
        view {masonite.view.View} -- 一般的 Masonite 视图类。

    返回值:
        self
    """
    pass

代码注释

如果你的代码必须足够复杂以至于将来的开发人员将无法理解它，请在其上方添加#注释。

对于一般的代码，它看起来像：

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

perform_some_complex_task()

拉取请求流程

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

1.在发出任何请求之前，您应该打开一个问题。并不是所有的功能都会被添加到框架中，有些功能作为第三方包可能会更好，或者根本就不会被添加。如果你在一个功能上工作了几天，而pull请求被拒绝的原因可能已经在一个问题上讨论了几分钟，那就不好了。
2.确保所有更改都有很好的注释，并且添加的任何配置文件都对其设置的变量有docstring注释。请参阅上面的评论部分。
3.更新MasoniteFramework/docsrepo(和自述.md在MasoniteFramework/masoniterepo(如果适用)内，提供对UI更改的详细信息。这包括新的环境变量、新的文件位置、容器参数、新的功能说明等。
4.以<feature | fix>/<issue number>的形式命名分支。例如，如果您正在执行错误修复，并且问题编号为576，则将您的分支命名为fix/576。这将有助于我们以后在计算机上查找分支。如果它是一个新的功能名称，它将功能/5765.必须为所做的任何更改添加单元测试。在上面列出的三个存储库中，只有masonite`repo需要单元测试。
6.增加任何示例文件和自述.md此请求将表示的新版本。我们使用的版本控制方案是RomVer.
7.PR必须通过Travis CI构建。一旦您从其他两个协作者处获得成功的评审，或者从维护者或Masonite创建者处获得一个评审，就可以合并Pull请求。

##分支

分支也很重要。根据你要执行的修复或功能，你需要从当前分支创建新分支 (然后合并回来) 。Masonite 分支的简单说明：

1) 所有 Masonite 仓库、代码包等都遵循相同的基本分支流程。
2) 每个仓库都有以下分支：当前发行分支，先前发行分支，主分支和开发分支。
3) 当前发行分支是当前发行版本所在的分支。所以如果 Masonite 当前版本为 2.3，则当前发行分支为 2.3。
4) 先前发行分支与此类似，是先前发行版本。所以如果 Masonite 当前版本为 2.3，则先前发行分支可能是 2.0、2.1、2.2 等。
5) 主分支是一个过渡分支，最终将合并到当前发行分支。所有非破坏性变更都会暂存在这里 (新的非破坏性功能和错误修复)。
6) 开发分支是到 下一个主要版本 的过渡分支。所以如果 Masonite 当前版本为 2.3，而你对某个功能有想法，但是它将破坏现有功能，那么你需要从 develop 分支创建新分支 (然后合并回来) 。develop 分支最终将合并到 2.4 版本并在发布时成为下一个主要版本的一部分。

示例：

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

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

添加新功能是一样的流程，但会从 develop 创建分支出来。你可以进行更改，然后打开对 develop 分支的拉取请求。这是一个长期运行的分支，一旦准备发布下一个主要版本的 Masonite 时，它将合并到主分支。

行为守则

我们的承诺

为了营造一个开放和热情的环境，我们作为贡献者和维护者保证，参与我们的项目和社区对每个人来说都是一种不受骚扰的体验，无论年龄，体重，残障，种族，性别认同和表达方式，经验水平，国籍，外貌，种族，宗教或性别认同和性取向如何。

我们的标准

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

• 使用友好和包容的语言
• 尊重不同的观点和经验
• 优雅地接受建设性的批评
• 关注对社区最有利的事物
• 与其他社区成员产生共鸣

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

• 使用色情语言或图片，以及不受欢迎的色情内容
• 钓鱼言论，侮辱性 / 贬损性评论以及人身或政治攻击
• 公开或私下骚扰
• 未经明确许可发布他人的私人信息，例如现实地址或电子邮件地址
• 其他在专业场合可能被合理的认为是不适当的行为

我们的责任

项目维护者有责任澄清可接受行为的标准，并应针对任何不可接受行为采取适当和公正的纠正措施。

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

范围

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

执行

可以通过 idmann509@gmail.com 与项目团队联系来举报侮辱、骚扰或其他不可接受的行为。所有的投诉都将接受审核和调查，并将根据情况做出必要和适当的回应。项目团队有责任为事件的举报人保密。具体实施政策的更多详细信息可能会单独发布。

不认真遵守或执行《行为准则》的项目维护者可能会面临由项目领导层其他成员决定的临时或永久性影响。

归属

本行为准则改编自 Contributor Covenant 1.4版，可以在 http://contributor-covenant.org/version/1/4 查看。

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

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

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