Contributing and Hacking

我编写ethers.js库是出于需要的,并且随着时间的推移已经有组织的发展起来。

很多事情都是有原因的(至少在当时),但我总是欢迎批评,并且完全愿意改变我对事情的看法。

申请拉取代码请求, 不过请记住几点:

一般来说, 在开始一个pull请求之前请先提出一个问题, 这样我们可以进行公开讨论,找出解决问题/功能的最佳办法:)

构建

不巧的是,以太坊的构建过程并不是超级简单的,但我已经试图使它尽可能的简单化。

这是一个mono repo,它试图与大量环境、构建工具和平台兼容,这就是为什么它必须做一些奇怪的事情

misc/admin文件夹中有几个自定义脚本可以帮助管理monorepo。开发人员通常不需要担心这些问题,因为 它们都是被npm 运行脚本 操作包裹封装的。

安装
# Clone the repository /home/ricmoo> git clone https://github.com/ethers-io/ethers.js.git /home/ricmoo> cd ethers.js # Install all dependencies: # - Hoists all sub-package dependencies in the package.json (preinstall) # - Installs all the (hoisted) dependencies and devDependencies (install) # - Build the rat-nests (in .package_node_modules) (postinstall) # - Create a dependency graph for the TypeScript (postinstall) # - Link the rat-nets into each project (postinstall) /home/ricmoo/ethers.js> npm install

进行更改

一旦你的环境设置好, 你应该能够简单地开启自动构建特性,并且能够修改TypeScript源代码.

Watching and Building
# 开始观察文件并在文件发生变化时重新构建 /home/ricmoo/ethers.js> npm run auto-build # 或者如果你不想观察而只是构建 /home/ricmoo/ethers.js> npm run build

创建浏览器适用的软件

要创建可以直接在浏览器中使用的文件,需要建立分布式的文件(位于packages/ethers/dist)需要被构建,这需要几个中间的构建、脚本和对于各种rollup脚本的执行.

Building Distribution Files
# 如果你需要重构所有的库(esm + cjs)和dist文件 # 注意:这需要node 10或者更新的 /home/ricmoo/ethers.js> npm run build-all

测试

测试
# 重构所有文件(npm run build-all)同时捆绑测试用例进行测试 /home/ricmoo/ethers.js> npm test # Often you don't need the full CI experience /home/ricmoo/ethers.js> npm run test-node

Distribution

大多数开发者不应该需要这个步骤,但对于分叉以太坊和创建替代物的人来说(例如,如果你有一个非EVM兼容链,但试图重新使用这个包)。

这个脚本将重建整个ether项目,将它与npm进行比较,重写包版本,更新内部哈希值,重写各种TypeScript文件(以绕过一些ES+TS对shake和链接的限制),重写映射文件,打包去除依赖的版本,基本上就是一堆东西。

如果你使用这个并且陷入了困境, 请给我发消息.

Preparing the Distribution
# Prepare all the distribution files # - Remove all generated files (i.e. npm run clean) # - Re-install all dependencies, hoisting, etc. (npm install) # - Spell check all strings in every TypeScript files # - Build everything from scratch with this clean install # - Compare local with npm, bumping the version if changed # - Build everything again (with the updated versions) # - Update the CHANGELOG.md with the git history since the last change /home/ricmoo/ethers.js> npm run update-version
Do NOT check in dist files in a PR

对于拉取代码的请求,请只提交docs.wrm/ andpackages/*/src.ts/文件夹下的文件。 我将自己准备发布构建 并且保持PR的相关性,这样更容易验证修改。

Publishing

同样,这对大多数开发者来说应该是没有必要的。这个步骤需要使用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

Preparing the Distribution
# Publish # - Update any changed packages to NPM # - Create a release on GitHub with the latest CHANGELOG.md description # - Upload the bundled files the the CDN # - Flush the CDN edge caches /home/ricmoo/ethers.js> npm run publish-all

文档

这些文件是用Flatworm文档生成工具生成的,该工具是为编写ethers的文档而编写的。

风格指南(这一章会有更多内容):

构建

要构建文档,您应该首先遵循以上步骤来构建ethers库.

构建文档将生成几种类型的输出:

构建文档
/home/ricmoo/ethers.js> npm run build-docs

评估

在构建文档时,所有的代码样本都会通过一个JavaScript虚拟机运行,以确保示例代码中没有错别字,同时也会将结果的准确输出注入到输出中,所以不需要保持结果和代码的同步。

然而,在做许多小的改动时,这可能是一个有点头痛的问题,所以为了更快地建立文档,你可以跳过评估步骤,这将直接注入代码。

创建跳过评估的文档
/home/ricmoo/ethers.js> npm run build-docs -- --skip-eval

预览更改

要在本地预览更改,你可以使用任何标准网络服务器并且从/docs/文件夹中运行, 或者使用内置的Web服务器

与普通网络开发一样的注意事项也适用,比如在修改(和重新构建)文档后,要刷新浏览器的缓存。在改变(和重新构建)文档后,要刷新浏览器缓存。

运行一个网络服务器
/home/ricmoo/ethers.js> npm run serve-docs