-
Notifications
You must be signed in to change notification settings - Fork 686
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
doc: Update README, add CONTRIBUTION & SECURITY (#2282)
* Fix README Fixes #2041 * Update readme more, added Contributing and Security policy * Fix few typos Co-authored-by: nearprotocol-bulldozer[bot] <56702484+nearprotocol-bulldozer[bot]@users.noreply.github.com>
- Loading branch information
1 parent
14c6e2d
commit 3393a09
Showing
3 changed files
with
168 additions
and
28 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| Thank you for considering contributing to the NEAR reference client! | ||
|
|
||
| We welcome all external contributions. This document outlines the process of contributing to nearcore. | ||
| For contributing to other repositories, see `CONTRIBUTING.md` in the corresponding repository. | ||
| For non-technical contributions, such as e.g. content or events, see [this document](https://docs.nearprotocol.com/docs/contribution/contribution-overview). | ||
|
|
||
| # Pull Requests and Issues | ||
|
|
||
| All the contributions to `nearcore` happen via Pull Requests. To create a Pull Request, fork `nearcore`, create a new branch, do the work there, and then send the PR via Github interface. | ||
|
|
||
| The PRs should always be against the `master` branch. | ||
|
|
||
| The exact process depends on the particular contribution you are making. | ||
|
|
||
| ## Typos or small fixes | ||
|
|
||
| If you see an obvious typo, or an obvious bug that can be fixed with a small change, in the code or documentation, feel free to submit the pull request that fixes it without opening an issue. | ||
|
|
||
| ## Working on current tasks | ||
|
|
||
| If you have never contributed to nearcore before, take a look at the work items in the issue tracker labeled with `good first issue` [here](https://github.com/nearprotocol/nearcore/labels/good%20first%20issue) and `good first test` [here](https://github.com/nearprotocol/nearcore/labels/good%20first%20test). If you see one that looks interesting, and is not claimed, please comment on the issue that you would like to start working on it, and someone from the team will assign it to you. | ||
|
|
||
| Keep in mind the following: | ||
|
|
||
| 1. The changes need to be thoroughly tested. Refer to [this document](https://github.com/nearprotocol/nearcore/wiki/Writing-tests-for-nearcore) for our testing guidelines and overview of the testing infrastructure. | ||
| 2. Because of (1), starting with a `good first test` task is a good idea, since it helps you familiarize yourself with the testing infrastructure. | ||
| 3. If you get an issue assigned to you, please post updates at least once a week. It is also preferred for you to send a draft PR as early as you have something working, before it is ready. | ||
|
|
||
| ### Submitting the PR | ||
|
|
||
| Once your change is ready, prepare the PR. The PR can contain any number of commits, but when it is merged, they will all get squashed. The commit names and descriptions can be arbitrary, but the name and the description of the PR must follow the following template: | ||
|
|
||
| ``` | ||
| <type>: <name> | ||
| <description> | ||
| Test plan | ||
| --------- | ||
| <test plan> | ||
| ``` | ||
|
|
||
| Where `type` is `fix` for fixes, `feat` for features, `refactor` for changes that primarily reorganize code, `doc` for changes that primarily change documentation or comments, and `test` for changes that primarily introduce new tests. The type is case sensitive. | ||
|
|
||
| The `test plan` should describe in detail what tests are presented, and what cases they cover. | ||
|
|
||
| ### After the PR is submitted | ||
|
|
||
| 1. We have a CI process configured to run all the sanity tests on each PR. If the CI fails on your PR, you need to fix it before it will be reviewed. | ||
| 2. Once the CI passes, you should expect the first feedback to appear within 48 hours. The reviewers will first review your tests, and make sure that they can convince themselves the test coverage is adequate before they even look into the change, so make sure you tested all the corner cases. | ||
| 3. Once you address all the comments, and your PR is accepted, we will take care of merging it. | ||
|
|
||
| ## Proposing new ideas and features | ||
|
|
||
| If you want to propose an idea or a feature and work on it, create a new issue in the `nearcore` repository. We presently do not have an issue template. | ||
|
|
||
| You should expect someone to comment on the issue within 48 hours after it is created. If the proposal in the issue is accepted, you should then follow the process for `Working on current tasks` above. | ||
|
|
||
| # Setting up the environment | ||
|
|
||
| We use nightly Rust features, so you will need nightly rust installed. See [this document](https://doc.rust-lang.org/1.2.0/book/nightly-rust.html) for details. | ||
|
|
||
| Majority of NEAR developers use CLion with Rust plugin as their primary IDE. | ||
|
|
||
| We also had success with VSCode with rust-analyzer, see the steps for installation [here](https://commonwealth.im/near/proposal/discussion/338-remote-development-with-vscode-and-rustanalyzer). | ||
|
|
||
| Some of us use VIM with [rust.vim](https://github.com/rust-lang/rust.vim) and [rusty-tags](https://github.com/dan-t/rusty-tags). It has fewer features than CLion or VSCode, but overall provides a usable setting. | ||
|
|
||
| Refer to [this document](https://docs.nearprotocol.com/docs/contribution/nearcore) for details on setting up your environment. | ||
|
|
||
| # Release Schedule | ||
|
|
||
| Once your change ends up in master, it will be released with the rest of the changes by other contributors on the regular release schedules. | ||
|
|
||
| You should expect the changes from `master` to get merged into `beta` branch the next time `nightly` test run completes, assuming it passes. | ||
| Releases to the `stable` branch are manual, but generally contain a contiguous prefix of commits from `beta` branch. | ||
| Note, that the goal is to maintain `beta` as stable as possible and `stable` completely stable. Hence if your change is breaking something that gets detected down the line - it will rolled back and requested to address the issue with additional test coverage. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| # Security Policy | ||
|
|
||
| Reference client for NEAR is held to highest security standard. | ||
| This document defines the policy how to report vulnerabilities and receive updates when security patches are released. | ||
|
|
||
| If you have any suggestions or comments about the security policy, please contact [NEAR Security Team](mailto:[email protected]). | ||
|
|
||
| ## Reporting a vulnerability | ||
|
|
||
| All security issues and questions should be reported by sending email to [NEAR Security Team](mailto:[email protected]). | ||
| This will be acknowledged within 24 hours by the NEAR Security Team and kick of review process. | ||
| You will receive a more detailed response to the email within 72 hours indicating perceived severity and the next steps in handling your report. | ||
|
|
||
| After initial reply to your report, the security team will keep your informed about the progress toward patching and public disclosure. | ||
|
|
||
| ## Handling & disclosure process | ||
|
|
||
| 1. Security report is received and assigned to an owner. This person will coordinate process of evaluating, fixing, releasing and disclosing the issue. | ||
| 2. After initial report received, the evaluation process is performed. It's identified if the issue exists, it's severity and which version / components of the code are affected. Additional review to identify similar issues also happens. | ||
| 3. Fixes are implemented for all supported releases. These fixes are not publicly communicated but held in private repo of Security Team or locally. | ||
| 4. A suggested announcement date for this vulnerability is chosen. The notification is drafted and includes patches to all supported versions and effected components. | ||
| 5. On the announcement date, the [NEAR Security Update newsletter](https://groups.google.com/a/nearprotocol.com/forum/#!forum/security-updates) is sent an announcement. The changes are fast tracked and merged into the public repository. At least 6 hours after the mailing list is notified, a copy of the advisory will be published across social channels. | ||
|
|
||
| This process may take time, especially when coordinating with network participants and maintainers of other components in the ecosystem. | ||
| The goal will be to address issues in as short period as possible, but it's important that the process described above to ensure that disclosures are handled in consistent manner. | ||
|
|
||
| *Note:* If Security Team identifies that an issue is mission critical and requires subset of network participants to update prior to newsletter announcement - this will be done in manual way by communicating via direct channels. | ||
|
|
||
| ## Receive Security Updates | ||
|
|
||
| If you are must be informed about security vulnerabilities, please subscribe to the [NEAR Security Update newsletter](https://groups.google.com/a/nearprotocol.com/forum/#!forum/security-updates). | ||
| The newsletter is very low traffic and only sent our where public disclosure of a vulnerability happens. |