ethers.js/docs.wrm/contributing.wrm

124 lines
4.1 KiB
Plaintext
Raw Normal View History

_section: Contributions and Hacking @<about-contrib> @priority<-90>
2022-12-31 01:01:15 +03:00
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.
2023-01-27 07:37:01 +03:00
Contributing to the documentation is welcome, but when making
changes to documentation, please ensure that all changes are
made **only** to:
2022-12-31 01:01:15 +03:00
- 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.
2023-01-27 07:37:01 +03:00
_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/
2023-10-10 03:28:22 +03:00
/home/ricmoo/flatworm> node lib/cli-test PATH_TO_WRM_ROOT
2023-01-27 07:37:01 +03:00
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.
2022-12-31 01:01:15 +03:00
_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.
2022-12-31 01:01:15 +03:00
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