89 lines
13 KiB
HTML
89 lines
13 KiB
HTML
<!DOCTYPE html>
|
|
<html class="paged">
|
|
<head>
|
|
<title>Contributing and Hacking</title>
|
|
<link rel="stylesheet" type="text/css" href="/v5/static/style.css">
|
|
</head>
|
|
<body>
|
|
<div class="sidebar">
|
|
<div class="header">
|
|
<div class="logo"><a href="/v5/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0</div></a></div>
|
|
</div>
|
|
<div class="toc"><div>
|
|
<div class="link title"><a href="/v5/">Documentation</a></div><div class="base show link depth-1"><a href="/v5/getting-started/">Getting Started</a></div><div class="base show link depth-1"><a href="/v5/concepts/">Ethereum Basics</a></div><div class="hide link depth-2"><a href="/v5/concepts/events/">Events</a></div><div class="hide link depth-2"><a href="/v5/concepts/gas/">Gas</a></div><div class="hide link depth-2"><a href="/v5/concepts/security/">Security</a></div><div class="base show link depth-1"><a href="/v5/api/">Application Programming Interface</a></div><div class="hide link depth-2"><a href="/v5/api/contract/">Contract Interaction</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract/">Contract</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract-factory/">ContractFactory</a></div><div class="hide link depth-3"><a href="/v5/api/contract/example/">Example: ERC-20 Contract</a></div><div class="hide link depth-2"><a href="/v5/api/signer/">Signers</a></div><div class="hide link depth-2"><a href="/v5/api/providers/">Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/provider/">Provider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/api-providers/">API Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/other/">Other Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/types/">Types</a></div><div class="hide link depth-2"><a href="/v5/api/utils/">Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/abi/">Application Binary Interface</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/coder/">AbiCoder</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/formats/">ABI Formats</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/fragments/">Fragments</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/interface/">Interface</a></div><div class="hide link depth-3"><a href="/v5/api/utils/address/">Addresses</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bignumber/">BigNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bytes/">Byte Manipulation</a></div><div class="hide link depth-3"><a href="/v5/api/utils/constants/">Constants</a></div><div class="hide link depth-3"><a href="/v5/api/utils/display-logic/">Display Logic and Input</a></div><div class="hide link depth-3"><a href="/v5/api/utils/encoding/">Encoding Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/fixednumber/">FixedNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hashing/">Hashing Algorithms</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hdnode/">HD Wallet</a></div><div class="hide link depth-3"><a href="/v5/api/utils/logger/">Logging</a></div><div class="hide link depth-3"><a href="/v5/api/utils/properties/">Property Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/signing-key/">Signing Key</a></div><div class="hide link depth-3"><a href="/v5/api/utils/strings/">Strings</a></div><div class="hide link depth-3"><a href="/v5/api/utils/transactions/">Transactions</a></div><div class="hide link depth-3"><a href="/v5/api/utils/web/">Web Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/wordlists/">Wordlists</a></div><div class="hide link depth-2"><a href="/v5/api/other/">Other Libraries</a></div><div class="hide link depth-3"><a href="/v5/api/other/assembly/">Assembly</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/api/">Utilities</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><div class="hide link depth-3"><a href="/v5/api/other/hardware/">Hardware Wallets</a></div><div class="hide link depth-2"><a href="/v5/api/experimental/">Experimental</a></div><div class="base show link depth-1"><a href="/v5/cli/">Command Line Interfaces</a></div><div class="hide link depth-2"><a href="/v5/cli/ethers/">Sandbox Utility</a></div><div class="hide link depth-2"><a href="/v5/cli/asm/">Assembler</a></div><div class="hide link depth-2"><a href="/v5/cli/ens/">Ethereum Naming Service</a></div><div class="hide link depth-2"><a href="/v5/cli/typescript/">TypeScript</a></div><div class="hide link depth-2"><a href="/v5/cli/plugin/">Making Your Own</a></div><div class="base show link depth-1"><a href="/v5/cookbook/">Cookbook</a></div><div class="base show link depth-1"><a href="/v5/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/v5/migration/web3/">Migration: From Web3.js</a></div><div class="hide link depth-2"><a href="/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="base show link depth-1"><a href="/v5/testing/">Testing</a></div><div class="base myself ancestor ancestor show link depth-1"><a href="/v5/contributing/">Contributing and Hacking</a></div><div class="base show link depth-1"><a href="/v5/documentation/">Flatworm Docs</a></div><div class="base show link depth-1"><a href="/v5/license/">License and Copyright</a></div>
|
|
</div></div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="breadcrumbs"><a href="/v5/">Documentation</a> » <span class="current">Contributing and Hacking</span></div>
|
|
|
|
<a name="contributing"></a><a name="contributing"></a><h1 class="show-anchors"><div>Contributing and Hacking<div class="anchors"><a class="self" href="/v5/contributing/#contributing"></a></div></div></h1><p>The ethers.js library is something that I've written out of necessity, and has grown somewhat organically over time.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>So, pull requests are always welcome, but please keep a few points in mind:</p>
|
|
|
|
<p><ul><li>Backwards-compatibility-breaking changes will not be accepted; they may be considered for the next major version </li><li>Security is important; adding dependencies require fairly convincing arguments as to why </li><li>The library aims to be lean, so keep an eye on the dist/ethers.min.js file size before and after your changes </li><li>Add test cases for both expected and unexpected input </li><li>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 </li></ul></p>
|
|
|
|
<p>In general, <b>please start an issue <i>before</i> beginning a pull request</b>, so we can have a public discussion and figure out the best way to address to problem/feature. <b>:)</b></p>
|
|
|
|
<a name="contributing--building"></a><a name="contributing--contributing--building"></a><h2 class="show-anchors"><div>Building<div class="anchors"><a class="self" href="/v5/contributing/#contributing--building"></a></div></div></h2><p>If you wish to modify the source code, there are a few steps involved in setting up your environment.</p>
|
|
|
|
<p>Since the library uses a monorepo, you must install an initial required set of libraries, which can then be used to install the remaining libraries used within each package, as well as link all the packages within the repo with each other.</p>
|
|
|
|
<div class="code-title"><div>Preparing for builds</div></div><div class="code"># Clone the repository
|
|
/home/ricmoo> git clone git@github.com:ethers-io/ethers.js.git
|
|
/home/ricmoo> cd ethers.js
|
|
|
|
# Install the base dependencies
|
|
/home/ricmoo/ethers.js> npm install
|
|
|
|
# Install each module's dependencies and link the libraries
|
|
# internally, so they reference each other
|
|
/home/ricmoo/ethers.js> npm run bootstrap</div><a name="contributing--updating"></a><a name="contributing--contributing--updating"></a><h2 class="show-anchors"><div>Making your changes<div class="anchors"><a class="self" href="/v5/contributing/#contributing--updating"></a></div></div></h2><p>TODO: Add more information here.</p>
|
|
|
|
<div class="code-title"><div>Watching and Building</div></div><div class="code"># Begin watching the files and re-building whenever they change
|
|
/home/ricmoo/ethers.js> npm run auto-build
|
|
|
|
|
|
# Sometimes the issue only affects the ESM modules
|
|
/home/ricmoo/ethers.js> npm run auto-build-esm
|
|
|
|
|
|
# Or if you only need to run a single build
|
|
/home/ricmoo/ethers.js> npm run _build-cjs
|
|
/home/ricmoo/ethers.js> npm run _build-esm</div><div class="code-title"><div>Testing</div></div><div class="code"># Rebuilds all files 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</div><div class="code-title"><div>Preparing the Distribution</div></div><div class="code">/home/ricmoo/ethers.js> npm run update-version</div><a name="contributing--documentation"></a><a name="contributing--contributing--documentation"></a><h2 class="show-anchors"><div>Documentation<div class="anchors"><a class="self" href="/v5/contributing/#contributing--documentation"></a></div></div></h2><p>The documents are generated using <a href="/v5/documentation/">Flatworm</a> documentation generation tool, which was written for the purpose of writing the documentation for ethers.</p>
|
|
|
|
<p>Style Guide (this section will have much more coming):</p>
|
|
|
|
<p><ul><li>Try to keep lines no longer than <i>around</i> 80 characters </li><li>Avoid inline links in the source; use the <code class="inline">externalLinks</code> field in the config.js </li><li>Prefix external links with <code class="inline">link-</code> </li><li>Changing an anchor name must be well justified, as it will break all existing links to that section; flatworm will support symblinks in the future </li><li>In general, I aim for xonsistency; look to similar situations throughout the documentation </li></ul></p>
|
|
|
|
<a name="contributing--contributing--documentation--building"></a><h3 class="show-anchors"><div>Building<div class="anchors"><a class="self" href="/v5/contributing/#contributing--contributing--documentation--building"></a></div></div></h3><p>To build the documentation, you should first follow the <a href="/v5/contributing/#contributing--building">above steps</a> to build the ethers library.</p>
|
|
|
|
<p>Building the docs will generate several types of output:</p>
|
|
|
|
<p><ul><li>A full set of HTML pages, linking across each other </li><li>A single one-page HTML page with all pages linking to local anchors </li><li>A full set of README.md pages organized to be browsable and linkable in GitHub </li><li>A metadata dump for tool ingestion (still needs more work) </li><li>(@TODO; only half done) The documentation as a LaTeX and generated PDF </li></ul></p>
|
|
|
|
<div class="code-title"><div>Building the Documentations</div></div><div class="code">/home/ricmoo/ethers.js> npm run build-docs</div><a name="contributing--contributing--documentation--evaluation"></a><h3 class="show-anchors"><div>Evaluation<div class="anchors"><a class="self" href="/v5/contributing/#contributing--contributing--documentation--evaluation"></a></div></div></h3><p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<div class="code-title"><div>Build docs skipping evaluation</div></div><div class="code">/home/ricmoo/ethers.js> npm run build-docs -- --skip-eval</div><a name="contributing--contributing--documentation--previewing-changes"></a><h3 class="show-anchors"><div>Previewing Changes<div class="anchors"><a class="self" href="/v5/contributing/#contributing--contributing--documentation--previewing-changes"></a></div></div></h3><p>To preview the changes locally, you can use any standard web server and run from the <code class="inline">/docs/</code> folder, or use the built-in web server.</p>
|
|
|
|
<p>The same caveats as normal web development apply, such flushing browser caches after changing (and re-building) the docs.</p>
|
|
|
|
<div class="code-title"><div>Running a webserver</div></div><div class="code">/home/ricmoo/ethers.js> npm run serve-docs</div>
|
|
|
|
<div class="footer">
|
|
<div class="nav previous"><a href="/v5/testing/"><span class="arrow">←</span>Testing</a></div>
|
|
<div class="nav next"><a href="/v5/documentation/">Flatworm Docs<span class="arrow">→</span></a></div>
|
|
</div>
|
|
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on July 5, 2020, 12:0am.</div>
|
|
</div>
|
|
<script src="/v5/static/script.js" type="text/javascript"></script>
|
|
</body>
|
|
</html>
|