|
1 | | -# Contributing to NEAR |
| 1 | +# Contributing to Near JavaScript SDK |
2 | 2 |
|
3 | | -NEAR welcomes help in many forms including development, code review, documentation improvements, and outreach. |
4 | | -Please visit [the contribution overview](https://docs.nearprotocol.com/docs/contribution/contribution-overview) for more information. |
| 3 | +First off, thanks for taking the time to contribute! We look forward to to your contributions. 🎉 |
5 | 4 |
|
6 | | -## Using Github issues and pull requests |
| 5 | +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. |
7 | 6 |
|
8 | | -Some repositories have specific issue templates that will be helpful for maintainers and community contributors. Please use the templates whenever available. |
| 7 | +We take community contributions very seriously, as we understand you invest precious time and effort. That is why we have this guide to set mutual expectations, to avoid unfortunate situation where we can't accept a contribution because it may not fit project's goals, or lacks needed quality standards. There is one important rule to follow - please let us know ahead about what you plan to do, and get an OK from our team so that we can prepare for accepting your contribution. |
9 | 8 |
|
10 | | -Please include steps to reproduction, if reporting an error. Information on all applicable versions is quite helpful. Some versions can be found using the command line. (For example: `node --version` or `rustc --version`.) Other version information may be packaged as dependencies. (For example: in `package.json` or `Cargo.toml`.) |
| 9 | +> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: |
| 10 | +> - Star the project |
| 11 | +> - Tweet about it |
| 12 | +> - Refer this project in your project's readme |
| 13 | +> - Mention the project at local meetups and tell your friends/colleagues |
11 | 14 |
|
12 | | -If there are verbosity flags available, please include those to offer as much information as possible. |
| 15 | +## Table of Contents |
13 | 16 |
|
14 | | -When opening a pull request, please use the typical open-source flow of forking the desired repository and opening a pull request from your forked repository. (More information on [technical contributions here](https://docs.nearprotocol.com/docs/contribution/technical-contribution).) |
| 17 | +- [I Have a Question](#i-have-a-question) |
| 18 | +- [Get Involved](#get-involved) |
| 19 | +- [Our Development Process](#our-development-process) |
| 20 | +- [Development](#development) |
| 21 | + - [Pull Requests](#pull-requests) |
| 22 | + - [Tests](#tests) |
| 23 | + - [What Happens Next?](#what-happens-next) |
15 | 24 |
|
16 | | -## Testing |
| 25 | +## I Have a Question |
17 | 26 |
|
18 | | -Please note that for technical contributions, NEAR runs a battery of continuous integration tools and tests for each pull request. |
| 27 | +If you want to ask a question please use the following resources available for you: |
19 | 28 |
|
20 | | -It's encouraged to write unit tests on new features. Many NEAR repositories have built-in scripts that run tests locally. Tests may check linting and must be addressed. |
| 29 | +- [Docs site](https://docs.near.org/sdk/js/introduction) |
| 30 | +- Post a question on [GitHub Discussions](https://github.com/near/near-sdk-js/discussions) |
| 31 | +- Post a question on [StackOverflow with `[nearprotocol]` tag](https://stackoverflow.com/questions/tagged/nearprotocol) |
21 | 32 |
|
22 | | -For this repository, please follow testing directions outlined in the `README.md` file. |
23 | 33 |
|
24 | | -### Thank you |
| 34 | +## Get Involved |
25 | 35 |
|
26 | | -NEAR values all contributors to the projects in the ecosystem and invites public discussion on the tech and vision. Please feel free to join the conversation using the links offered at [near.help](https://near.help). |
| 36 | +There are many ways to contribute to this project, and many of them do not involve writing any code. Here's a few ideas to get started: |
| 37 | + |
| 38 | +- Simply start using the library. Go through the [user guide](https://docs.near.org/sdk/js/introduction). Does everything work as expected? If not, we're always looking for improvements. Let us know on [GitHub Discussions](https://github.com/near/near-sdk-js/discussions). |
| 39 | +- Look through the [open issues](https://github.com/near/near-sdk-js/issues). Provide workarounds or ask for clarification. |
| 40 | +- If you find an issue you would like to fix, [open a pull request](#pull-requests). Issues tagged as [_Good first issue_](https://github.com/near/near-sdk-js/labels/good_first_issue) are a good place to get started. |
| 41 | +- Take a look at the [enhancements requested](https://github.com/near/near-sdk-js/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on. |
| 42 | + |
| 43 | +If you think you need help planning your contribution, please ping us on [Discord](https://near.chat) and let us know you are looking for a bit of help. |
| 44 | + |
| 45 | +### Join our Discord Channel |
| 46 | + |
| 47 | +We have the [`#dev-feedback`](https://discord.gg/XKGrd9h9TB) channel on [Discord](https://near.chat) to discuss all things about NEAR development. You can also be of great help by helping other users in the [`#dev-support`](https://discord.gg/Fy4WzwRgun) channel. |
| 48 | + |
| 49 | +### Join our Telegram User Group |
| 50 | +You can have near-sdk-js related discussions with other users, contributors and maintainers on [Telegram]( https://t.me/near_sdk_js). |
| 51 | + |
| 52 | +### Triaging Issues and Pull Requests |
| 53 | + |
| 54 | +One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in. |
| 55 | + |
| 56 | +You can review code, or ask for more information if you believe the issue does not provide all the details required to solve it. |
| 57 | + |
| 58 | +## Our Development Process |
| 59 | + |
| 60 | +Our core team works directly in the public repo, and pull requests are checked by the continuous integration system, GitHub actions. There are unit tests and end-to-end tests. |
| 61 | + |
| 62 | +**Branch organization**: This project has one primary branch `develop` and we use feature branches to deliver new features with pull requests. |
| 63 | + |
| 64 | +**Issue templates**: When [opening a new issue](https://github.com/near/near-sdk-js/issues/new/choose), always **make sure to fill out the issue template**. The issue template is very important, as it sets mutual expectations about what you plan to do, and help us prepare to accept your contribution. |
| 65 | + |
| 66 | +**Bugs**: If you would like to report a problem use the [bug report](https://github.com/near/near-sdk-js/issues/new?assignees=&template=bug.yml) issue template. |
| 67 | + |
| 68 | +**Security Bugs **: To report security issues in this project please email [[email protected]](mailto:[email protected]) |
| 69 | + |
| 70 | +**New features and enhancements**: |
| 71 | + |
| 72 | +If you have a casual feature request or proposal, you can raise it in our [GitHub Discussions](https://github.com/near/near-sdk-js/discussions/categories/ideas). |
| 73 | + |
| 74 | +If you'd like to work on a PR with an implementation of your proposal, please file an issue with the [feature template](https://github.com/near/near-sdk-js/issues/new?template=feature.yml) in the form of an **elaborated RFC**. Please wait for our team to respond with an approval before you start working on it, as we can only accept PRs that are aligned with project's goals and roadmap, so we really want to avoid situations where we reject something you worked hard on. (BTW, if you think that project's goals or roadmap should change in some way, do feel free to raise it in [GitHub Discussions](https://github.com/near/near-sdk-js/discussions/) :) and we'll talk about it). |
| 75 | + |
| 76 | +### Claiming issues |
| 77 | + |
| 78 | +We have a list of [beginner-friendly issues](https://github.com/near/near-sdk-js/labels/good_first_issue) to help you get started with the codebase and get familiar with our contribution process. This is a great place to start. |
| 79 | + |
| 80 | +Apart from the `good first issue`, the following labels are also worth looking at: |
| 81 | + |
| 82 | +- [`help wanted`](https://github.com/near/near-sdk-js/labels/help%20wanted): if you have specific knowledge in one domain, working on these issues can make your expertise shine. |
| 83 | +- [`accepting pr`](https://github.com/near/near-sdk-js/labels/status%3A%20accepting%20pr): community contributors can feel free to claim any of these. |
| 84 | + |
| 85 | +If you want to work on any of these issues, just drop a message saying "I'd like to work on this", and we will assign the issue to you and update the issue's status as "claimed". **You are expected to send a pull request within seven days** after that, so we can still delegate the issue to someone else if you are unavailable. |
| 86 | + |
| 87 | +## Development |
| 88 | + |
| 89 | +### Online one-click setup for contributing |
| 90 | + |
| 91 | +You can use Gitpod (a free, online, VSCode-like IDE) for contributing. With a single click, it will launch a workspace and automatically: |
| 92 | + |
| 93 | +- clone the repo. |
| 94 | +- install the dependencies. |
| 95 | + |
| 96 | +So that you can start contributing straight away. |
| 97 | + |
| 98 | +[](https://gitpod.io/#https://github.com/near/near-sdk-js) |
| 99 | + |
| 100 | +## Pull Requests |
| 101 | + |
| 102 | +We appreciate the time and effort you invested! 🙏 We will do our best to work with you and get the PR looked at. |
| 103 | + |
| 104 | +> Working on your first-ever Pull Request? You can learn how from this free video series: |
| 105 | +> [**How to Contribute to an Open Source Project on GitHub**](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) |
| 106 | +
|
| 107 | +Please make sure the following is done when submitting a pull request: |
| 108 | + |
| 109 | +1. **Keep your PR small.** Small pull requests (~300 lines of diff) are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. |
| 110 | +2. **Use descriptive titles.** It is recommended to follow semantic commit conventions: https://www.conventionalcommits.org/en/v1.0.0/ |
| 111 | +3. **Test your changes.** Include unit tests for any public API you touch. |
| 112 | + |
| 113 | +All pull requests should be opened against the `develop` branch. |
| 114 | + |
| 115 | +### Tests |
| 116 | + |
| 117 | +Please include unit tests for any public api you add or touch. We use [AVA](https://github.com/avajs/ava) for tests. |
| 118 | + |
| 119 | +### What Happens Next? |
| 120 | + |
| 121 | +Our team will be monitoring pull requests. Do help us by keeping pull requests consistent by following the guidelines above. |
0 commit comments