Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

如何针对 ECMAScript 规范创建一个拉取请求 #8626

Merged
merged 6 commits into from
May 25, 2021
Merged

如何针对 ECMAScript 规范创建一个拉取请求 #8626

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9bb7e3e
translation done
PassionPenguin May 20, 2021
a9d7292
Apply suggestions from code review
PassionPenguin May 24, 2021
841b00b
Update article/ECMA-TC39/How-to-make-a-Pull-Request-against-the-ECMAS…
PassionPenguin May 24, 2021
decfdeb
Update article/ECMA-TC39/How-to-make-a-Pull-Request-against-the-ECMAS…
PassionPenguin May 24, 2021
94a4b2a
Update article/ECMA-TC39/How-to-make-a-Pull-Request-against-the-ECMAS…
PassionPenguin May 24, 2021
5d15ad3
Update article/ECMA-TC39/How-to-make-a-Pull-Request-against-the-ECMAS…
PassionPenguin May 24, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 28 additions & 30 deletions ...le/ECMA-TC39/How-to-make-a-Pull-Request-against-the-ECMAScript-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,58 +2,56 @@
> * 原文作者：[Ecma TC39](https://github.com/tc39/how-we-work)
> * 译文出自：[掘金翻译计划](https://github.com/xitu/gold-miner)
> * 本文永久链接：[https://github.com/xitu/gold-miner/blob/master/article/ECMA-TC39/How-to-make-a-Pull-Request-against-the-ECMAScript-specification.md](https://github.com/xitu/gold-miner/blob/master/article/ECMA-TC39/How-to-make-a-Pull-Request-against-the-ECMAScript-specification.md)
> * 译者：
> * 校对者：
>
> * 译者：[霜羽 Hoarfroster](https://github.com/PassionPenguin)、[Usualminds](https://github.com/Usualminds)
> * 校对者：[Usualminds](https://github.com/Usualminds)
PassionPenguin marked this conversation as resolved.
Show resolved Hide resolved

# How to make a Pull Request against the ECMAScript specification
# 如何针对 ECMAScript 规范创建一个拉取请求

All changes to the JavaScript specification ultimately become a pull request (PR) against the [ecma262](https://github.com/tc39/ecma262/) or [ecma402](https://github.com/tc39/ecma402/) repositories.
对 JavaScript 规范的所有更改最终都会变为对 [ecma262](https://github.com/tc39/ecma262/) 或 [ecma402](https://github.com/tc39/ecma402/) 存储库的拉取请求。

## Making a PR
## 创建一个拉取请求

To make a pull request (PR), [fork](https://help.github.com/articles/fork-a-repo/) the [ecma262](https://github.com/tc39/ecma262), apply changes to the spec.html, and upload it to your fork on GitHub, using the web interface to file a pull request. Locally, to see how your change renders in HTML, use `npm run build` (via [ecmarkup](https://github.com/bterlson/ecmarkup)) to build spec.html into an actual HTML file.
要创建一个请求请求（PR），请 [fork](https://help.github.com/articles/fork-a-repo/) [ecma262](https://github.com/tc39/ecma262) 仓库，将变更添加到 spec.html 文件，并将其上传到 GitHub 上之前 fork 的仓库中，使用 Web 端界面提交拉取请求。在本地编辑时，要想查看你在 HTML 中的内容更改，请运行 `npm run build`（通过 [ecmarkup](https://github.com/bterlson/ecmarkup)）将 spec.html 生成为实际的 HTML 文件。
PassionPenguin marked this conversation as resolved.
Show resolved Hide resolved

**Which repo should the PR target?**: Almost all specifications PRs should target the ecma262 repo; ecma402 is just used for the Intl specification, which provides a standard library for internationalization.
**拉取请求应指定哪个仓库？**：几乎所有规范内容的拉取请求都应针对 ecma262 仓库；ecma402 仓库仅用于存储国际规范（提供国际化的标准库）。

Commits in pull requests should have a first line which starts with a tag, followed by a colon, indicating which type of patch they are:
拉取请求中的提交的第一行应该以以下的标记开头，后跟冒号，以说明它们是哪一种修补（patch）类型：

* `Normative:` changes impacting JavaScript behavior in some way. These changes are called "observable" because it is possible to write code to "observe" the change in behavior.
* `Editorial:` any non-normative changes to spec text including typo fixes, changes to the document style, etc.
* `Layering:` refactoring of specification text, algorithms, and/or embedder hooks to enable clean integration of the JavaScript specification with other specifications that use JavaScript.
* `Markup:` non-visible changes to markup in the spec
* `Meta:` changes to documents about this repository (e.g. readme.md or contributing.md) and other supporting documents or scripts (e.g. package.json, design documents, etc.)
* `Normative:` 变化会以某种方式影响 JavaScript 的行为。这些更改被称为“可观察的”，因为我们可以通过编写代码来“观察”其行为的变化。
* `Editorial:` 对规范文本进行的任何非规范性更改，包括拼写错误、文档样式的更改等。
* `Layering:` 重构规范文本、算法或嵌入钩子的修改，以实现 JavaScript 规范与其他使用 JavaScript 规范的无入侵式的集成。
* `Markup:` 对规范中的标记不可见的更改
* `Meta:` 更改了有关该存储库的文档（例如 readme.md 或 contributing.md）以及其他支持文档或脚本（例如 package.json，设计文档等）

## Stage 4 proposal PRs (`Normative:`)
## 第四阶段提案拉取请求（`Normative:`）

Stage 4 of the [TC39 Stage Process](http://tc39.es/process-document/) requires a proposal to be written up as a PR against the specification; a review of this PR from the [editor group](https://github.com/tc39/how-we-work/blob/master/management.md#ecma-262-editor-group) is required to reach Stage 4, and after Stage 4, the PR is merged.
[TC39 阶段流程](http://tc39.es/process-document/) 的第四阶段要求将建议书写成与规范相对应的拉取文本；要进入第四阶段，需要[编辑组](https://github.com/tc39/how-we-work/blob/master/management.md#ecma-262-editor-group)针对该拉取请求进行审查，并在第四阶段之后合并该拉取请求。

## Non-normative PRs
## 非规范拉取请求

Editorial, Layering, Markup, and Meta PRs do not change how JavaScript behaves, but they are useful for people who are reading or working with the JavaScript specification.
`Editorial`、`Layering`、`Markup` 和 `Meta` 类型的拉取请求不会更改 JavaScript 的行为，但是它们对于正在阅读或使用 JavaScript 规范的人员却很有意义。

If you have a change that you'd like to make to the JavaScript specification, either file an issue for initial discussion, or go straight to putting a PR out for review. Oftentimes, the review can be conducted purely on GitHub, involving the editors and anyone else who wants to participate. Since there is no observable change to JavaScript, these PRs don't require the explicit consensus of the committee, but they may be brought to committee if they are controversial.
如果您要对 JavaScript 规范进行更改，请提出 Issue 进行初步讨论，或者直接创建拉取请求并请求审核。通常，针对拉取请求的审核可以完全在 GitHub 上进行，编者和任何其他想要参与的人都可以参与审核。由于 JavaScript 不会有明显的变化，因此这些拉取请求不需要委员会的明确共识，但是，如果出现了争议，则可以将这个拉取请求提交到委员会，交由委员会处理。

## Normative PRs
## 规范性拉取请求

Normative PRs change what JavaScript programs do, potentially requiring action to adjust from both JavaScript engine implementers as well as developers who program in JavaScript. This is serious business! For this reason, Normative PRs have the following requirements:
规范性拉取请求更改了 JavaScript 程序的功能，可能需要采取行动才能从 JavaScript 引擎实现者以及使用 JavaScript 进行编程的开发者那里进行调整。这是很严肃的事情！因此，规范的拉取请求具有以下要求：

- There must be tests proposed in [test262](https://github.com/tc39/test262/) for the PR.
- The PR must be brought up in committee. In some cases, this can be a quick description by editors or the author, and if no concerns are raised, the proposal is considered to "have consensus". Other times, if the proposal is controversial, it's useful to [prepare a presentation](https://github.com/tc39/how-we-work/blob/master/presenting.md) explaining the motivation in more detail, with a discussion following it to discuss whether the committee can come to consensus on the proposal. For this reason, controversial normative PRs are tagged "needs consensus".
- 必须在 [test262](https://github.com/tc39/test262/) 中提出针对拉取请求的所做的测试。
- 拉取请求必须在委员会中提出。在某些情况下，编者或作者只需对 PR 进行简短描述，如果没有提出任何疑问，则认为该提案“已达成共识”。在其他时候，如果该提案有争议，则需要[准备演示文稿](https://github.com/tc39/how-we-work/blob/master/presenting.md)，更详细地说明动机（这很是有用）。随后将进行讨论，并且委员会将会针对是否可以就该提案达成共识作出回应。因此，有争议的规范性拉取请求会被标记为“需要共识”（`needs consensus`）。

If you have a PR that you've proposed, and you'd like to push it forward, write test262 tests for it and put it on the agenda for an upcoming TC39 meeting. If you're not on the committee, it's important to find a TC39 delegate to champion the proposal and help push it through the committee's process, including giving the presentation.
如果您有拟议的拉取请求，并且希望将其推进，请为其编写 test262 测试，并将其放在即将举行的 TC39 会议的议程上。如果您不在委员会中，对你而言重要的事情是要找到一个 TC39 代表来支持该提案，并在委员会的整个过程中（包括进行演示）将其推进。

It is encouraged for TC39 delegates to proactively add "needs consensus" PRs to an upcoming meeting agenda and present them; if one is not available, the editors, as time permits, will add these to the agenda.
我们鼓励 TC39 代表们在即将到来的会议议程上主动添加“需要共识”的拉取请求，并对其进行介绍。如果没有人主动提出该拉取请求，编者将在时间允许的情况下将其添加到议程中。

### "Web reality" PRs
### "网络与现实" 拉取请求

Occasionally, there is a mismatch noticed between what the JavaScript specification says, and what most or all web browsers implement. Given the large quantity of code on the web, there's a decent chance that there are already many websites which expect the unspecified, but broadly shipping, behavior. In these sorts of cases, the most useful thing to do is often to change the specification, rather than change all of the JavaScript implementations, to match "web reality".
有时，JavaScript 规范与大多数或所有 Web 浏览器实现的内容之间会出现不匹配的情况。鉴于网络上的大量代码，很有可能已经有许多网站期望这种行为，但是却没有明确说明，但大体上是部署了的。在这种情况下，最有用的事情通常是更改规范，而不是更改所有 JavaScript 实现，以匹配“网络现实”。

### Implementation feedback
### 实施反馈

In many cases, it's useful to have some feedback about how realistic it is to implement a Normative PR, whether implementations are interested in making some kinds of non-trivial changes, etc. For these cases, the committee may ask for one or more implementations (possibly just in a fork or behind a flag) before merging a Normative PR.
在许多情况下，收集有关实施规范的拉取请求的现实状况、是否实现对某些不太重要的修改感兴趣等方面，获取外界的反馈是有用的。对于这些情况，委员会可能会要求构建一个或多个实现（可能只是在 fork 中或被隐藏在 flag 中），然后再合并规范拉取请求。

> 如果发现译文存在错误或其他需要改进的地方，欢迎到 [掘金翻译计划](https://github.com/xitu/gold-miner) 对译文进行修改并 PR，也可获得相应奖励积分。文章开头的 **本文永久链接** 即为本文在 GitHub 上的 MarkDown 链接。
---
> [掘金翻译计划](https://github.com/xitu/gold-miner) 是一个翻译优质互联网技术文章的社区，文章来源为 [掘金](https://juejin.im) 上的英文分享文章。内容覆盖 [Android](https://github.com/xitu/gold-miner#android)、[iOS](https://github.com/xitu/gold-miner#ios)、[前端](https://github.com/xitu/gold-miner#前端)、[后端](https://github.com/xitu/gold-miner#后端)、[区块链](https://github.com/xitu/gold-miner#区块链)、[产品](https://github.com/xitu/gold-miner#产品)、[设计](https://github.com/xitu/gold-miner#设计)、[人工智能](https://github.com/xitu/gold-miner#人工智能)等领域，想要查看更多优质译文请持续关注 [掘金翻译计划](https://github.com/xitu/gold-miner)、[官方微博](http://weibo.com/juejinfanyi)、[知乎专栏](https://zhuanlan.zhihu.com/juejinfanyi)。