124 lines
4.1 KiB
Plaintext
124 lines
4.1 KiB
Plaintext
_section: Contributions and Hacking @<about-contrib> @priority<-90>
|
|
|
|
Pull requests are welcome, but please keep the following 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 (the ``build-clean`` target includes these stats)
|
|
- Keep the PR simple, readable and confined to the relevant
|
|
files; see below for which files to change
|
|
- 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
|
|
- Everyone is working hard; **be kind and respectful**
|
|
|
|
It is always //highly recommended// that you open a [[link-discussion]]
|
|
**before** beginning a PR.
|
|
|
|
|
|
_subsection: Documentation @<about-contrib-docs>
|
|
|
|
The documentation is an area which can always benefit from extra
|
|
eyes, extra knowledge and extra examples.
|
|
|
|
Contributing to the documentation is welcome, but when making
|
|
changes to documentation, please ensure that all changes are
|
|
made **only** to:
|
|
|
|
- Updating ``/docs.wrm/*\*.wrm``
|
|
- Adding links: ``/docs.wrm/links/*.txt``
|
|
- Updating API jsdocs: ``/*\* ... */`` comment blocks within ``/src.ts/``
|
|
|
|
Generally changes to ``/docs.wrm/config.wrm`` should not be
|
|
made, and if you feel it is necessary, please consider opening
|
|
a [[link-discussion]] first.
|
|
|
|
Similarly, when adding a new sections, a [[link-discussion]] is
|
|
preferred.
|
|
|
|
All changes should be in the Flatworm Markdown Dialect.
|
|
|
|
_heading: Building the Documentation
|
|
|
|
Currently, the documentation is built using an experimental v2 of the
|
|
Flatworm documentation system, a system originally specifically made
|
|
to maintain the Ethers documentation.
|
|
|
|
The new ``tsdocs`` branch has the ability to parse ``jsdocs`` from
|
|
from TypeScript source files to create an API reference.
|
|
|
|
_code: Building with the v2 Flatworm @lang<shell>
|
|
|
|
# Clone the repo
|
|
/home/ricmoo> git clone https://github.com/ricmoo/flatworm.git
|
|
/home/ricmoo> cd flatworm
|
|
|
|
# Check out the tsdocs branch
|
|
/home/ricmoo/flatworm> git checkout tsdocs
|
|
|
|
# Install the necessary dependencies
|
|
/home/ricmoo/flatworm> npm install
|
|
|
|
# Ready to build the docs; output to a folder ./output/
|
|
/home/ricmoo/flatworm> node lib/cli-test PATH_TO_WRM_ROOT
|
|
|
|
Eventually the code for the v2 branch will be cleaned up, and it
|
|
will be much easier to include as a ``devDependency`` for Ethers.
|
|
|
|
In the meantime, expect new changes to be made frequently to the
|
|
``tsdocs`` branch, so for stability you may wish to checkout a
|
|
specific hash.
|
|
|
|
|
|
_subsection: Fixing Bugs @<about-contrib-bugs>
|
|
|
|
In general the **only** files you should ever include in a PR are:
|
|
|
|
- TypeScript source: ``/src.ts/*\*.ts``
|
|
|
|
Do not include a ``package.json`` with the updated ``tarballHash``
|
|
or ``version``, and do not include any generated files in your PR.
|
|
|
|
A bug fix **must not** modify anything requiring a minor version
|
|
bump (see [[about-contrib-feature]]), such as changing a method
|
|
signature or altering the exports.
|
|
|
|
|
|
_subsection: Adding Features @<about-contrib-feature>
|
|
|
|
Contributing new features usually require a deeper understanding
|
|
of the internal interactions with Ethers and its components, and
|
|
generally requires a minor version bump.
|
|
|
|
When making any of the following changes, you must first open a
|
|
[[link-discussion]] as the minor version will need to be bumped.
|
|
|
|
- any signature change (such as adding a parameter, changing a
|
|
parameter type, changing the return type)
|
|
- adding any new export; such as a class, function or constants
|
|
- adding any method to any class
|
|
- changing any ``exports`` property within the ``package.json``
|
|
|
|
Changes of this sort should not be made without serious consideration
|
|
and discussion.
|
|
|
|
|
|
_subsection: Building @<building>
|
|
|
|
_code: @lang<shell>
|
|
/home/ricmoo> git clone @TODO
|
|
/home/ricmoo> cd ethers
|
|
/home/ricmoo/ethers> npm install
|
|
/home/ricmoo/ethers> npm run auto-build
|
|
|
|
_null:
|
|
|
|
|
|
_subsection: Previewing Documentation
|
|
|