我编写ethers.js库是出于需要的,并且随着时间的推移已经有组织的发展起来。
很多事情都是有原因的(至少在当时),但我总是欢迎批评,并且完全愿意改变我对事情的看法。
申请拉取代码请求, 不过请记住几点:
- 破坏后向兼容性的改变将不会被接受;它们可能主要考虑的是下一个主要版本
- 安全是很重要的; adding dependencies require fairly convincing arguments as to why
- 这个库的目标是精简,所以在修改之前和之后都要注意dist/ether.min.js文件的大小
- 保持PR简单易读; 只修改
docs.wrm/
和packages/*/src.ts/
文件夹中的文件,因为这样可以方便地验证更改 - 为预期的和意外的输入添加测试用例
- 任何新特性都需要我的支持(未来问题、文档、测试、迁移),所以任何过于复杂或特定的特性都可能不被接受
一般来说, 在开始一个pull请求之前请先提出一个问题, 这样我们可以进行公开讨论,找出解决问题/功能的最佳办法:)
不巧的是,以太坊的构建过程并不是超级简单的,但我已经试图使它尽可能的简单化。
这是一个mono repo,它试图与大量环境、构建工具和平台兼容,这就是为什么它必须做一些奇怪的事情
misc/admin
文件夹中有几个自定义脚本可以帮助管理monorepo。开发人员通常不需要担心这些问题,因为 它们都是被npm 运行脚本
操作包裹封装的。
一旦你的环境设置好, 你应该能够简单地开启自动构建
特性,并且能够修改TypeScript源代码.
要创建可以直接在浏览器中使用的文件,需要建立分布式的文件(位于packages/ethers/dist
)需要被构建,这需要几个中间的构建、脚本和对于各种rollup脚本的执行.
大多数开发者不应该需要这个步骤,但对于分叉以太坊和创建替代物的人来说(例如,如果你有一个非EVM兼容链,但试图重新使用这个包)。
这个脚本将重建整个ether项目,将它与npm进行比较,重写包版本,更新内部哈希值,重写各种TypeScript文件(以绕过一些ES+TS对shake和链接的限制),重写映射文件,打包去除依赖的版本,基本上就是一堆东西。
如果你使用这个并且陷入了困境, 请给我发消息.
对于拉取代码的请求,请只提交docs.wrm/
andpackages/*/src.ts/
文件夹下的文件。 我将自己准备发布构建 并且保持PR的相关性,这样更容易验证修改。
同样,这对大多数开发者来说应该是没有必要的。这个步骤需要使用misc/admin/cmds/config-set
脚本来设置一些值, 包括私钥、NPM会话密钥、AWS访问密钥。GitHub API令牌,等等
配置文件是用大约30秒的基于scrypt密码的,密钥推导功能进行加密,因此对该文件进行暴力破解代价是相当昂贵的
配置文件还包含一个纯文本的助记符。这是个money-pot(钱罐子)。在这个账户上放置一笔一定数量的以太币或比特币,并为这个账户设置一个 为这个账户设置电子邮件警报。
任何攻击者都会在你的加密配置中遇到,他们可以立即访问明文助记符,因此他们可以选择立即窃取以太网(i.e. the responsible-disclosure bond)。
如果你看到这个以太坊被盗,你的加密文件就讲会被破坏。Rotate all your AWS keys, NPM session keys, etc. immedately.
@TODO: document all the keys that need to be set for each step
这些文件是用Flatworm文档生成工具生成的,该工具是为编写ethers的文档而编写的。
风格指南(这一章会有更多内容):
- 尽量保持行的长度不超过大约80个字符
- 避免在源代码中使用内联链接;使用config.js中的
externalLinks
字段 - 用
link-
作为外部链接的前缀 - 更改锚定名称必须合乎情理,因为它将中断该部分的所有链接,flatworm在未来将支持符号链接
- 一般来说,我的目标是一致性;在整个文档中寻找类似的情况
要构建文档,您应该首先遵循以上步骤来构建ethers库.
构建文档将生成几种类型的输出:
- 一套完整的HTML页面,相互链接
- 一个单页HTML页面,所有页面都链接到本地锚点
- 整套的README.md页面,在GitHub中可以浏览和链接。
- 元数据转储,用于工具摄取(仍需更多工作)
- (@TODO;只完成了一半)以LaTeX和生成的PDF格式的文档
在构建文档时,所有的代码样本都会通过一个JavaScript虚拟机运行,以确保示例代码中没有错别字,同时也会将结果的准确输出注入到输出中,所以不需要保持结果和代码的同步。
然而,在做许多小的改动时,这可能是一个有点头痛的问题,所以为了更快地建立文档,你可以跳过评估步骤,这将直接注入代码。
要在本地预览更改,你可以使用任何标准网络服务器并且从/docs/
文件夹中运行, 或者使用内置的Web服务器
与普通网络开发一样的注意事项也适用,比如在修改(和重新构建)文档后,要刷新浏览器的缓存。在改变(和重新构建)文档后,要刷新浏览器缓存。