Thank you for contributing to Web3.js! We appreciate your interest and welcome any contributions that can help improve our documentation, functionality, address bugs, or any other aspects that can contribute to the overall improvement of our project. Before you start contributing, please take a moment to review the guidelines below.
If you face any issues while contributing or want any type of support, we encourage you to join our Discord Community, ask any question in the #web3js-general
channel, and/or submit a new issue.
-
Fork the docs: Start by forking our repository to your GitHub account.
-
Clone the repo: Clone the forked repository to your local machine using the following command:
git clone https://github.com/your-username/web3.js.git
- Create a Branch: Create a new branch for your changes with a descriptive name. NOTE: The branch name must include the issue number (if there is no issue created for your contribution, please create one).
git checkout -b issue-name-1234
-
Navigate to the docs folder:
cd web3.js/docs/docs
-
Install dependencies:
yarn
-
Make your changes:...
-
Check changes in the local environment: Run the command
yarn start
and you'll see a local environment inlocalhost:3000
with the documents. -
Commit your changes:
git add .
andgit commit -m 'descriptive msg'
-
Push your changes:
git push origin branch-name
-
Open a Pull Request (PR): Provide a detailed description of your changes, the problem you are solving, and any additional context (you can use the PR template).
-
Wait for review: Before merging any branch into the main branch, it must be approved by two devs, after it is successfully approved, you can
Squash and merge
your branch, Please be responsive to any feedback on your pull request and make necessary changes based on the review.
This document provides some ground rules for contributors (including the maintainer(s) of the project) about how to make, review and publish changes to 4.x. The most basic requirement is that Web3 not break.
- Any PR that introduces a logic change should include tests. (In many cases, the tests will take more time to write than the actual code).
- All PRs should sit for 72 hours with the
please review
tag to garner feedback. - No PR should be merged until it has been reviewed, passes CI, and all reviews' comments are addressed.
- PRs should:
- have a narrow, well-defined focus.
- make the smallest set of changes possible to achieve their goal.
- include a clear description in the opening comment.
- preserve the conventions and stylistic consistency of any files they modify.
- Given the choice between a conservative change that mostly works and an adventurous change that seems better but introduces uncertainty - prefer the conservative change.
The end goal of the review is to suggest useful improvements to the author. Reviews should finish with approval unless there are issues that would result in:
- Buggy behavior.
- Undue maintenance burden.
- Pessimisation (i.e. speed reduction or meaningful build-size increases).
- Feature reduction (i.e. it removes some aspect of functionality that users rely on).
- Avoidable risk (i.e. it's difficult to test or hard to anticipate the implications of, without being strictly necessary to fix something broken).
Read more in Review Guidelines.
- All releases should be proposed in a PR and subject to community review for a minimum of one week.
- Release review periods should be accompanied by a published
rc
version which can be used for sanity checks / additional testing. - During release review, the code is frozen unless new changes are proposed, approved and merged.
- Changes should trigger a new
rc
release and set the release clock back enough that reviewers have the time they need to test new changes. - Regular maintainers should manually test the
rc
against a Node project and the published minified bundle in a browser context. An external reviewer should verify they've done the same. - A release PR must be approved at least by two known contributors to the web3.js project.
Read more in the Release Guidelines.
Emergency releases are allowed to shorten waiting periods depending on the severity of the issue.
There is precedent set for this in the 1.2.6 release (see #3351), where the consensus view was to make the smallest change necessary to address the emergency while waiving the rc
process (meaning many existing additions to master were excluded).
This topic is under further org-wide discussion at ethereum/js-organization#6.