From 74b7c84d201a5713f108d1ba34497eae7c23c5c8 Mon Sep 17 00:00:00 2001 From: T3 Code Service User Date: Thu, 17 Sep 2026 00:09:22 +0000 Subject: [PATCH] docs(contributing): limit compat fixes to inputs Lodash's types allow or real code passes Co-Authored-By: Claude Fable 5.1 --- .github/CONTRIBUTING-ko_kr.md | 9 ++++++++- .github/CONTRIBUTING-zh_hans.md | 9 ++++++++- .github/CONTRIBUTING.md | 9 ++++++++- 3 files changed, 24 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING-ko_kr.md b/.github/CONTRIBUTING-ko_kr.md index 96310be88..758dbd6d6 100644 --- a/.github/CONTRIBUTING-ko_kr.md +++ b/.github/CONTRIBUTING-ko_kr.md @@ -188,7 +188,14 @@ Pull Request의 제목은 다음 형식을 따라 주세요. #### Lodash와 다른 동작 고치기 -**환영해요.** `es-toolkit/compat`에 해당하는 이야기예요. compat은 Lodash와 똑같이 동작하는 게 존재 이유라서, 다른 값을 돌려주면 마이그레이션하는 프로젝트가 원인을 찾기 어려운 방식으로 깨져요. +Lodash의 타입이 허용하는 입력에 대한 수정은 환영해요. `es-toolkit/compat`은 Lodash와 똑같이 동작하는 게 중요해요. 다른 값을 돌려주면 마이그레이션하는 프로젝트가 원인을 찾기 어려운 방식으로 깨지거든요. + +다만 Lodash에는 문자열 자리에 `null`이나 숫자를 넘기는 것처럼 잘못된 입력을 처리하는 오래된 동작들이 있어요. 이런 동작 하나하나가 타입이 있는 프로젝트에서는 작성할 수조차 없는 호출을 위해, 아주 자주 실행되는 코드에 분기를 더해요. 그래서 다음 중 하나에 해당할 때만 차이를 고치는 PR을 받아요: + +1. **TypeScript `strict` 모드에서 `@types/lodash`로 컴파일되는 호출이에요.** 재현 코드를 `import { fn } from 'lodash'`로 작성하고 `tsc`로 확인해 주세요. 타입이 호출을 거부하면 그 차이는 범위 밖이에요. +2. **실제 코드가 그렇게 호출하고 있어요.** 그런 입력을 넘기는 GitHub 공개 저장소 파일의 permalink를 링크해 주세요. 다른 사람들이 쓰는 프로젝트여야 해요. 버그를 보여 주려고 만든 저장소, 포크, 그리고 Lodash 자체 테스트 코드는 안 돼요. Lodash 테스트는 Lodash가 어떻게 동작하는지 보여 줄 뿐, 누가 어떻게 쓰는지 보여 주지는 않으니까요. + +둘 다 해당하지 않으면 수정이 맞더라도 PR을 닫아요. 차이를 말로 설명하지 말고 코드로 보여 주세요. 어떤 입력에 대해 Lodash는 무엇을 돌려주고, 지금 `es-toolkit/compat`은 무엇을 돌려주는지 적어 주세요. 그리고 변경 전에는 실패하고 변경 후에는 통과하는 테스트를 함께 추가해 주세요. 나중에 다시 어긋나지 않게 하기 위해서예요. 고치려는 함수가 자주 호출되는 코드라면 벤치마크 결과도 붙여 주세요. compat 수정은 많이 실행되는 코드에 분기를 더하는 경우가 많거든요. diff --git a/.github/CONTRIBUTING-zh_hans.md b/.github/CONTRIBUTING-zh_hans.md index 4b1d6cb40..1dc2de7dc 100644 --- a/.github/CONTRIBUTING-zh_hans.md +++ b/.github/CONTRIBUTING-zh_hans.md @@ -183,7 +183,14 @@ discussion 被接受之后，请在拉取请求中一并提供实现、测试、 #### 修复与 Lodash 不一致的行为 -**欢迎。** 这针对的是 `es-toolkit/compat`。与 Lodash 行为完全一致正是 compat 存在的意义——一旦返回值不同，正在迁移的项目就会以很难排查的方式出问题。 +我们欢迎针对 Lodash 自身类型所允许的输入的修复。`es-toolkit/compat` 与 Lodash 行为完全一致非常重要——一旦返回值不同，正在迁移的项目就会以很难排查的方式出问题。 + +不过，Lodash 也支持一些遗留行为，例如在字符串位置传入 `null` 或数字这类无效输入。每一项这样的行为都会给频繁执行的代码增加分支，而对应的调用在有类型的项目里根本写不出来。因此，只有满足以下至少一条时，我们才接受修复这类差异： + +1. **该调用能在 TypeScript `strict` 模式下通过 `@types/lodash` 的编译。** 请以 `import { fn } from 'lodash'` 的形式编写复现代码，并用 `tsc` 检查。如果类型拒绝了这个调用，这个差异就不在范围内。 +2. **真实代码里存在这样的调用。** 请链接到 GitHub 公开仓库中传入这类输入的文件 permalink。它必须是其他人在使用的项目：不能是你为了展示 bug 而创建的仓库，不能是 fork，也不能是 Lodash 自己的测试代码——测试只说明 Lodash 如何运行，并不说明有人如何使用它。 + +如果两条都不满足，即使修复本身是正确的，我们也会关闭这个拉取请求。 请用代码展示差异，而不是用文字描述：对于同一个输入，Lodash 返回什么，现在的 `es-toolkit/compat` 又返回什么。同时补上一个在改动前会失败、改动后会通过的测试，这样行为就不会再次跑偏。如果你改动的函数位于热点路径，请一并附上基准测试结果——compat 的修复往往会给频繁执行的代码增加分支。 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 27faec5ef..110ea7f11 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -184,7 +184,14 @@ Our benchmarks use [Vitest's benchmark feature](https://vitest.dev/api/#bench) a #### Fixing behavior that differs from Lodash -**Welcome.** This applies to `es-toolkit/compat`, where matching Lodash exactly is the entire point—if we return something different, migrating projects break in ways that are hard to trace. +We welcome contributions for inputs that Lodash's own types allow. It is important for `es-toolkit/compat` to match Lodash exactly since if we return something different, migrating projects break in ways that are hard to trace. + +However, there are some legacy behaviors that Lodash supports, such as handling invalid inputs such as `null` or numbers in positions of strings. Each of these adds branches to code that runs very often, for a call no typed project can write. So we accept a difference only when at least one of the following holds: + +1. **The call compiles against `@types/lodash` in TypeScript `strict` mode.** Write the reproduction as `import { fn } from 'lodash'` and check it with `tsc`. If the types reject the call, the difference is out of scope. +2. **Real code makes the call.** Link to a permalink of a file in a public repository on GitHub that passes such input. It has to be a project that others use, not a repository you created to show the bug, not a fork, and not Lodash's own test suite, which describes how Lodash behaves rather than how anyone uses it. + +If neither applies, we close the pull request even when the fix is correct. Show the difference as code instead of describing it: the exact input, what Lodash returns for it, and what `es-toolkit/compat` returns today. Add a test that fails before your change and passes after it, so the behavior stays fixed. If the function you are touching runs in a hot path, attach benchmark results as well—these fixes tend to add branches to code that runs very often.