贡献 Express
想要为 Expressjs.com 贡献力量?请点击此处。
Express 以及 GitHub 上的 expressjs 组织中的其他项目均是 OpenJS 基金会的项目。这些项目遵循 Node.js 基金会的通用政策和准则,以及以下附加准则的约束。
技术委员会
Express 技术委员会由活跃的项目成员组成,负责指导 Express 项目的开发和维护。欲了解更多信息,请参阅Express 社区 - 技术委员会。
社区贡献指南
本文档的目标是创建一个贡献流程,该流程应
- 鼓励新的贡献。
- 鼓励贡献者持续参与。
- 尽可能避免不必要的流程和官僚主义。
- 创建透明的决策过程,明确贡献者如何参与决策。
词汇表
- 贡献者是指创建或评论议题或拉取请求的任何个人。
- 提交者是获得仓库写入权限的贡献者子集。
- 项目负责人是仓库的首席维护者。
- TC(技术委员会)是由提交者组成的团体,代表解决罕见争议所需的技术专业知识。
- 问题分类者是获得仓库问题分类权限的贡献者子集。
提交议题
对于您可能遇到的任何问题或疑问,请提交议题。如有疑问,请提交议题,关于包含哪些内容的任何附加政策将在回复中提供。唯一的例外是安全披露,应私下发送。
在议题处理之前,提交者可能会将您引导至另一个仓库,要求提供额外的澄清,并添加适当的元数据。
请务必礼貌和尊重。每位参与者都应遵守项目的行为准则。
贡献
本仓库中资源的任何更改都必须通过拉取请求进行。这适用于文档、代码、二进制文件等所有更改。即使是长期提交者和技术委员会成员也必须使用拉取请求。
未经审查,任何拉取请求都不能合并。
对于非简单的贡献,拉取请求应至少保留 36 小时,以确保其他时区的贡献者有时间审查。还应考虑周末和其他节假日,以确保活跃的提交者如果愿意,都有合理的时间参与讨论和审查过程。
每项贡献的默认情况是,一旦没有提交者提出异议,即被接受。在审查期间,提交者也可能要求在特定领域最精通的贡献者在拉取请求合并前给出“LGTM”(Looks Good To Me)。贡献没有额外的“签署”流程。一旦提交者提出的所有问题都得到解决,任何提交者都可以将其落地。
如果另一个提交者在拉取请求中提出异议,所有相关的提交者都应通过讨论、对提议的更改进行妥协或撤回提议的更改来寻求达成共识。
如果一项贡献存在争议,并且提交者无法就如何或是否使其落地达成一致,则应将其上报给技术委员会 (TC)。技术委员会成员应定期讨论待处理的贡献,以找到解决方案。预计只有极少数问题会提交给技术委员会解决,而提交者之间的讨论和妥协应是默认的解决机制。
成为问题分类者
任何人都可以成为问题分类者!在问题分类流程文档中阅读更多关于成为问题分类者的信息。
目前,任何现有的组织成员都可以提名新的问题分类者。如果您有兴趣成为问题分类者,我们最好的建议是通过帮助分类议题和拉取请求来积极参与社区。同时,我们建议您参与其他社区活动,例如参加技术委员会会议和参与 Slack 讨论。如果您觉得准备好了并且一直在帮助分类一些议题,请联系组织的活跃成员,询问他们是否愿意支持您。如果他们同意,他们可以创建一个拉取请求来正式化您的提名。如果对提名有异议,问题分类团队负责与相关人员合作并找到解决方案。
如果您有疑问或需要指导,也可以联系任何组织成员。
成为提交者
所有已做出重大和有价值贡献的贡献者应及时加入,并被添加为提交者,并获得仓库的写入权限。
提交者应遵循此政策,并继续发送拉取请求,进行适当审查,并由其他提交者合并其拉取请求。
技术委员会流程
技术委员会对上报的问题采用“寻求共识”的流程。该小组会尝试找到一个在技术委员会成员中没有公开反对意见的解决方案。如果无法达成没有异议的共识,则会进行多数票决。同时,技术委员会的大多数决定预计通过寻求共识的流程做出,投票仅作为最后手段使用。
解决方案可能包括将问题返回给项目负责人,并提供关于如何达成共识的建议。技术委员会的会议不期望在一次会议中解决其议程上的所有问题,并且可能更倾向于继续项目负责人之间的讨论。
成员可以随时加入技术委员会。任何技术委员会成员都可以提名另一位提交者加入技术委员会,技术委员会将使用其标准的寻求共识流程来评估是否添加此新成员。技术委员会将由最少 3 名活跃成员和最多 10 名成员组成。如果技术委员会成员少于 5 名,活跃的技术委员会成员应提名新成员。如果技术委员会成员辞职,他们被鼓励(但非强制)提名某人接替他们的位置。
技术委员会成员将根据需要被添加为 GitHub 组织、npm 组织和其他资源的管理员,以便有效履行其职责。
为保持“活跃”,技术委员会成员应在过去 12 个月内有所参与,并且连续缺席的技术委员会会议不得超过六次。我们的目标是增加参与度,而不是惩罚任何缺乏参与的人,本指南应仅用于此类目的(例如,用一个新的活跃成员替换一个不活跃的成员)。不符合此条件的成员应辞职。如果技术委员会成员不辞职,可以在讨论仓库中提出一个议题,将其移至非活跃状态。辞职或因不活跃而被移除的技术委员会成员将被移至非活跃状态。
如果技术委员会成员数量尚未超过 10 人的上限,非活跃状态的成员可以通过自荐成为活跃成员。如果技术委员会已达到最大规模且有活跃成员辞职,他们也将获得优先考虑。
项目负责人
Express 技术委员会可以为组织中的单个项目/仓库指定负责人。这些负责人负责在技术和社区方面担任仓库的日常主要维护者。仓库负责人拥有仓库所有权和包发布权限。当出现冲突时,特别是影响整个 Express 项目的议题,负责人有责任将其上报给技术委员会并推动这些冲突的解决。负责人还负责确保社区成员遵守社区准则,维护仓库和已发布的包,并提供用户支持。
与技术委员会成员一样,仓库负责人是提交者的一个子集。
要成为项目负责人,候选人需在提出请求之前,以提交者身份在该项目参与至少 6 个月。他们应协助代码贡献和问题分类。此外,他们的 GitHub 和 npm 账户都必须启用双重身份验证 (2FA)。
任何技术委员会成员或在相同仓库中现有的负责人都可以提名另一位提交者担任负责人角色。为此,他们应向本文档提交一个拉取请求,更新活跃项目负责人部分(同时保持排序顺序),其中包含项目名称、被提名人的 GitHub 句柄及其 npm 用户名(如果不同)。
- 仓库可以根据工作范围拥有任意数量的负责人。
- 技术委员会成员或同一项目的现有仓库负责人可以提名新的负责人。来自其他项目的仓库负责人不应提名不同项目的负责人。
该拉取请求将需要至少 2 名技术委员会成员的批准,并有 2 周的保留时间以允许评论和/或异议。拉取请求合并后,技术委员会成员将把他们添加到适当的 GitHub/npm 组中。
活跃项目和负责人
当前倡议负责人
开发者原创证书 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
协作者指南
网站问题
在 https://github.com/expressjs/expressjs.com 中提交 expressjs.com 网站的议题。
对于其他 Express 管理的仓库(expressjs
、pillarjs
或 jshttp
中除 expressjs/express
之外的所有内容)中的问题,请务必查看其贡献指南并在相应的仓库中提交议题和拉取请求。
拉取请求和代码贡献
- 测试必须通过。
- 遵循JavaScript Standard Style 和运行
npm run lint
。 - 如果您修复了一个 bug,请添加测试。
分支
对于错误修复或针对当前发布流的次要工作,请使用 master
分支。
对于计划在 Express 未来版本中发布的内容,请使用相应的命名分支,例如 6.x
。
贡献步骤
- 为您要修复的错误或要添加的功能创建一个议题。
- 在 GitHub 上创建您自己的派生仓库,然后检出您的派生仓库。
- 在您的本地副本中编写代码。为每个您正在处理的新议题创建一个分支是一个好习惯,尽管并非强制性。
- 要运行测试套件,请首先运行
npm install
安装依赖项,然后运行npm test
。 - 通过运行
npm run lint
确保您的代码已通过 lint 检查 – 修复您看到的所有列出的问题。 - 如果测试通过,您可以将更改提交到您的派生仓库,然后从那里创建拉取请求。请务必在拉取请求评论中通过包含议题编号(例如
#123
)来引用您的议题。
问题类议题
我们通常会关闭任何模糊的议题或针对您正在编写的某个应用程序的问题。在急于发布问题议题之前,请务必仔细检查文档和其他参考资料。
有助于您的提问议题得到关注的事项
- 完整且可运行的 JS 代码。
- 清晰描述问题或意外行为。
- 清晰描述预期结果。
- 您自己已采取的调试步骤。
如果您提出问题但未能概述上述事项,或者未能使我们容易理解和重现您的问题,该议题将被关闭。
如果您的问题符合上述所有要求,但您认为无需维护者查看(例如,如果您只是寻求社区意见),请将其作为讨论主题而不是议题提出。如果您不确定并提交了一个议题,如果我们对其进行分类并认为它们不需要高可见性或维护者输入,我们可能会将其移至讨论区。
安全政策和程序
本文档概述了 Express 项目的安全程序和一般政策。
报告错误
Express 团队和社区认真对待 Express 中的所有安全漏洞。感谢您为提高 Express 的安全性所做的贡献。我们感谢您的努力和负责任的披露,并将尽一切努力认可您的贡献。
通过电子邮件报告安全漏洞至 [email protected]
。
为确保及时回复您的报告,请确保报告的全部内容包含在电子邮件正文中,而不是仅通过网页链接或附件提供。
首席维护者将在 48 小时内确认您的电子邮件,并在 48 小时内发送更详细的回复,说明处理您报告的后续步骤。在对您的报告进行初步回复后,安全团队将努力让您了解修复和完整公告的进展情况,并可能要求提供额外信息或指导。
向维护模块的个人或团队报告第三方模块中的安全漏洞。
预发布版本
Alpha 和 Beta 版本不稳定,不适合生产环境使用。在预发布版本中发现的漏洞应按照报告错误部分进行报告。由于分支的不稳定性,不保证在下一个预发布版本中发布任何修复程序。
披露政策
当安全团队收到安全漏洞报告时,他们会将其分配给主要处理人。此人将协调修复和发布过程,包括以下步骤:
- 确认问题并确定受影响的版本。
- 审计代码以查找任何潜在的类似问题。
- 为所有仍在维护的版本准备修复程序。这些修复程序将尽快发布到 npm。
Express 威胁模型
我们目前正在开发新版安全模型,最新版本可在此处找到。
对本政策的评论
如果您对如何改进此流程有任何建议,请提交拉取请求。
为 Expressjs.com 贡献
Express JS 框架的官方文档
这是 expressjs.com 网站的贡献文档。
需要一些想法?这些是一些典型的问题。
- 网站问题:如果您在网站上看到任何可以改进的地方,请思考如何修复它。
- 显示或屏幕尺寸问题
- 移动响应性问题
- 缺失或损坏的可访问性功能
- 网站中断
- 死链接
- 页面结构或用户界面增强
- 内容问题:修复与网站内容或拼写错误相关的任何问题。
- 拼写错误
- 不正确/过时的 Express JS 文档
- 内容缺失
- 翻译问题:修复任何翻译错误或贡献新内容。
- 修复拼写错误
- 修复不正确/翻译不佳的词语
- 请查看下面的贡献翻译部分以获取贡献指南。
想处理积压的议题吗?
我们经常有需要处理的错误或增强功能。您可以在我们仓库的议题选项卡下找到这些。查看标签以找到适合您的内容。
有想法?发现了一个错误?
如果您发现了一个错误或拼写错误,或者您有增强功能的想法,您可以
-
在我们的仓库上提交一个新议题。对于大型提案,或者如果您想先讨论或获取反馈,请这样做。
-
发起一个Github 拉取请求。如果您已经完成了工作并且准备就绪,请随时发送给我们。
开始
以下步骤将指导您完成 Expressjs.com 的贡献流程。
步骤 1:(可选)开启新议题
因此,您发现了一个想修复的问题,或者想对网站进行一项增强。
- 如果您想获取反馈或进行讨论,请在开始工作前开启一个讨论议题。这不是强制性的,但对于大型提案来说是鼓励的。
- 虽然我们强烈鼓励这一步,但它仅适用于提出重大更改的提交。它有助于我们澄清和集中工作,并确保其与整体项目优先级保持一致。
- 对于提出小幅改进或更正的提交,则无需此步骤。您可以跳过此步骤。
- 开启议题时,请为其提供标题并填写描述部分。您提供的细节越多,我们能提供的反馈就越多。
- 收到您的议题后,Express JS 文档团队将回复反馈。我们阅读每一份提交,并始终努力快速提供反馈。
- 对于提出重大更改的提交,我们鼓励您在开始工作之前遵循审查流程。
步骤 2:获取应用程序代码库
克隆仓库并获取代码
git clone https://github.com/expressjs/expressjs.com.git
获取代码后,您就可以开始进行更改了!
但以防万一您需要额外解释,下面的这部分概述了代码库的主要部分,其中最有可能进行更改。
Markdown 页面文件:
- 这些文件渲染为 HTML,构成了网站的各个页面。网站的大部分文档文本内容都以
md
文件格式编写。 - 更改这些文件以修改单个页面的内容/文本或标记。
- 每种语言都有其完整的页面集,位于各自的语言目录下——例如,所有西班牙语的 markdown 内容都可以在
es
目录下找到。
包含的局部和布局模板
_includes
是导入并在多个页面中重用的局部文件。- 它们用于导入文本内容以在页面间重用,例如 API 文档,例如
_includes > api > en > 5x
,它包含在每种语言中。 - 它们用于包含构成全站用户界面和外围结构(例如页眉、页脚等)的页面组件。
- 它们用于导入文本内容以在页面间重用,例如 API 文档,例如
_layouts
是用于包装网站各个页面的模板。- 它们用于显示网站外围结构(如页眉和页脚),以及在
content
标签内注入和显示单个 markdown 页面。
- 它们用于显示网站外围结构(如页眉和页脚),以及在
博客 Markdown 文件
- 这些文件构成了各个博客文章。如果您想贡献一篇博客文章,请遵循如何撰写博客文章中的具体说明。
- 位于
_posts
目录下。
CSS 或 Javascript
- 所有 CSS 和 JS 文件都保存在项目根目录下的
css
和js
文件夹中。
Express JS 网站使用 Jekyll 构建,并托管在 Github Pages 上。
步骤 3:运行应用程序
现在您需要一种方法来查看您的更改,这意味着您需要一个运行中的应用程序版本。您有两种选择。
- 本地运行:这将在您的机器上启动并运行应用程序的本地版本。请遵循我们的本地设置指南来使用此选项。
- 这是针对中等到复杂工作的推荐选项。
- 使用部署预览运行:如果您不想麻烦进行本地安装,请使用此选项。我们的持续集成管道包括 Netlify 部署预览。
- 要使用此功能,您需要将更改上线——在您的功能分支上进行首次提交后,发起一个草稿拉取请求。
- 构建步骤完成后,您将可以访问“部署预览”选项卡,该选项卡将在网页上运行您的更改,并在每次推送提交后重新构建。
- 当您完全完成工作并准备好进行审查时,请移除拉取请求的草稿状态并提交您的工作。
贡献翻译
我们使用 Crowdin 管理多种语言的翻译,并通过人工智能实现自动翻译。由于这些翻译在某些情况下可能效率不高,我们需要社区的帮助来提供准确且有用的翻译。
文档已翻译成以下语言:
- 简体中文 (
zh-cn
) - 繁体中文 (
zh-tw
) - 英语 (
en
) - 法语 (
fr
) - 德语 (
de
) - 意大利语 (
it
) - 日语 (
ja
) - 韩语 (
ko
) - 巴西葡萄牙语 (
pt-br
) - 西班牙语 (
es
)
如何翻译
- 请求加入 Crowdin 上的 Express.js 网站项目
- 选择您想要翻译的语言
- 开始翻译