224 lines
8.4 KiB
Plaintext
224 lines
8.4 KiB
Plaintext
_section: Contributing and Hacking @<contributing>
|
|
|
|
The ethers.js library is something that I've written out of necessity,
|
|
and has grown somewhat organically over time.
|
|
|
|
Many things are the way they are for good (at the time, at least) reasons,
|
|
but I always welcome criticism, and am completely willing to have my mind
|
|
changed on things.
|
|
|
|
Pull requests are always welcome, but please keep a few points in mind:
|
|
|
|
- Backwards-compatibility-breaking changes will not be accepted; they may be
|
|
considered for the next major version
|
|
- Security is important; adding dependencies require fairly convincing
|
|
arguments as to why
|
|
- The library aims to be lean, so keep an eye on the dist/ethers.min.js
|
|
file size before and after your changes
|
|
- Keep the PR simple and readable; only modify files in the ``docs.wrm/``
|
|
and ``packages/*/src.ts/`` folders, as this allows the changes to be easily
|
|
verified
|
|
- Add test cases for both expected and unexpected input
|
|
- Any new features need to be supported by me (future issues, documentation,
|
|
testing, migration), so anything that is overly complicated or specific
|
|
may not be accepted
|
|
|
|
In general, **please start an issue //before// beginning a pull request**, so we can
|
|
have a public discussion and figure out the best way to address the problem/feature.
|
|
**:)**
|
|
|
|
|
|
_subsection: Building @<contributing--building>
|
|
|
|
The build process for ethers is unfortunatly not super trivial, but
|
|
I have attempted to make it as straight-forward as possible.
|
|
|
|
It is a mono-repo which attempts to be compatibile with a large
|
|
number of environments, build tools and platforms, which is why
|
|
there are a some weird things it must do.
|
|
|
|
There are several custom scripts in the ``misc/admin`` folder
|
|
to help manage the monorepo. Developers working on contributing
|
|
to ethers should not generally need to worry about those, since
|
|
they are wrapped up behind ``npm run SCRIPT`` operations.
|
|
|
|
_code: Installing @lang<shell>
|
|
|
|
# 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
|
|
|
|
_heading: Making Changes @<contributing--updating>
|
|
|
|
Once your environment is set up, you should be able to simply
|
|
start the ``auto-build`` feature, and make changes to the
|
|
TypeScript source.
|
|
|
|
_code: Watching and Building @lang<shell>
|
|
|
|
# Begin watching the files and re-building whenever they change
|
|
/home/ricmoo/ethers.js> npm run auto-build
|
|
|
|
# Or if you do not want to watch and just build
|
|
/home/ricmoo/ethers.js> npm run build
|
|
|
|
_heading: Creating Browser-Ready Files
|
|
|
|
To create files for use directly in a browser, the distribution
|
|
files (located in ``packages/ethers/dist``) need to be built
|
|
which requires several intermediate builds, scripts and for
|
|
various rollup scripts to execute.
|
|
|
|
_code: Building Distribution Files @lang<shell>
|
|
|
|
# If you need to rebuild all the libs (esm + cjs) and dist files
|
|
# Note: this requires node 10 or newer
|
|
/home/ricmoo/ethers.js> npm run build-all
|
|
|
|
_heading: Testing
|
|
|
|
_code: Testing @lang<shell>
|
|
|
|
# Rebuilds all files (npm run build-all) and bundles testcases up for testing
|
|
/home/ricmoo/ethers.js> npm test
|
|
|
|
# Often you don't need the full CI experience
|
|
/home/ricmoo/ethers.js> npm run test-node
|
|
|
|
_heading: Distribution
|
|
|
|
Most developers should not ever require this step, but for people
|
|
forking ethers and creating alternates (for example if you have
|
|
a non-EVM compatible chain but are trying to reuse this package).
|
|
|
|
This script will rebuild the entire ethers project, compare it
|
|
against npm, re-write package versions, update internal hashes,
|
|
re-write various TypeScript files (to get around some ES+TS
|
|
limitations for Tree Shaking and linking), re-write map files,
|
|
bundle stripped versions of dependencies and basically just a
|
|
whole bunch of stuff.
|
|
|
|
If you use this and get stuck, [message me](link-mail).
|
|
|
|
_code: Preparing the Distribution @lang<shell>
|
|
|
|
# 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
|
|
|
|
_note: Do NOT check in dist files in a PR
|
|
|
|
For Pull Requests, please ONLY commit files in the ``docs.wrm/`` and
|
|
``packages/*/src.ts/`` folders. I will prepare the distribution builds
|
|
myself and keeping the PR relevant makes it easier to verify the changes.
|
|
|
|
_heading: Publishing
|
|
|
|
Again, this should not be necessary for most developers. This step
|
|
requires using the ``misc/admin/cmds/config-set`` script for a number
|
|
of values, including private keys, NPM session keys, AWS access keys,
|
|
GitHub API tokens, etc.
|
|
|
|
The config file is encrypted with about 30 seconds of scrypt password-based
|
|
key derivation function, so brute-forcing the file is quite expensive.
|
|
|
|
The config file also contains a plain-text mnemonic. This is a money-pot.
|
|
Place a tempting amount of ether or Bitcoin on this account and set up an
|
|
e-mail alert for this account.
|
|
|
|
If any attacker happens across your encrypted config, they will have instant
|
|
access to the plain-text mnemonic, so they have the option to immediately
|
|
steal the ether (i.e. the responsible-disclosure bond).
|
|
|
|
If you ever see this ether taken, your encrypted file is compromised! Rotate
|
|
all your AWS keys, NPM session keys, etc. immedately.
|
|
|
|
@TODO: document all the keys that need to be set for each step
|
|
|
|
_code: Preparing the Distribution @lang<shell>
|
|
|
|
# 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
|
|
|
|
|
|
_subsection: Documentation @<contributing--documentation>
|
|
|
|
The documents are generated using [Flatworm](flatworm) documentation
|
|
generation tool, which was written for the purpose of writing the documentation
|
|
for ethers.
|
|
|
|
Style Guide (this section will have much more coming):
|
|
|
|
- Try to keep lines no longer than //around// 80 characters
|
|
- Avoid inline links in the source; use the ``externalLinks`` field in the config.js
|
|
- Prefix external links with ``link-``
|
|
- Changing an anchor name must be well justified, as it will break all existing links
|
|
to that section; flatworm will support symlinks in the future
|
|
- In general, I aim for consistency; look to similar situations throughout the documentation
|
|
|
|
|
|
_heading: Building
|
|
|
|
To build the documentation, you should first follow the
|
|
[above steps](contributing--building) to build the ethers library.
|
|
|
|
Building the docs will generate several types of output:
|
|
|
|
- A full set of HTML pages, linking across each other
|
|
- A single one-page HTML page with all pages linking to local anchors
|
|
- A full set of README.md pages organized to be browsable and linkable in GitHub
|
|
- A metadata dump for tool ingestion (still needs more work)
|
|
- (@TODO; only half done) The documentation as a LaTeX and generated PDF
|
|
|
|
_code: Building the Documentations @lang<shell>
|
|
|
|
/home/ricmoo/ethers.js> npm run build-docs
|
|
|
|
|
|
_heading: Evaluation
|
|
|
|
When building the documentation, all code samples are run through a JavaScript
|
|
VM to ensure there are no typos in the example code, as well the exact output
|
|
of results are injected into the output, so there is no need to keep the results
|
|
and code in-sync.
|
|
|
|
However, this can be a bit of a headache when making many small changes, so to
|
|
build the documentation faster, you can skip the evaluation step, which will
|
|
inject the code directly.
|
|
|
|
_code: Build docs skipping evaluation @lang<shell>
|
|
|
|
/home/ricmoo/ethers.js> npm run build-docs -- --skip-eval
|
|
|
|
|
|
_heading: Previewing Changes
|
|
|
|
To preview the changes locally, you can use any standard web server and run
|
|
from the ``/docs/`` folder, or use the built-in web server.
|
|
|
|
The same caveats as normal web development apply, such flushing browser
|
|
caches after changing (and re-building) the docs.
|
|
|
|
_code: Running a webserver @lang<shell>
|
|
|
|
/home/ricmoo/ethers.js> npm run serve-docs
|