Core/grin
0
0
Fork 0
mirror of https://github.com/mimblewimble/grin.git synced 2025-01-21 03:21:08 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #2440 from sesam/CONTRIBUTING-update-from-wiki

Browse source 
Contributing update from wiki
This commit is contained in:
hashmap 2019-01-24 10:08:06 +01:00 committed by GitHub
commit 329d243ccd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 50 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
CONTRIBUTING.md
View file

@ -2,7 +2,7 @@
Find an area you can help with and do it. Open source is about collaboration and open participation. Try to make your code look like what already exists and submit a pull request.
The [list of issues](https://github.com/mimblewimble/grin/issues) is a good place to start, especially the ones tagged as "help wanted" (but don't let that stop you from looking at others). If you're looking for additional ideas, the code includes `TODO` comments for minor to major improvements. Grep is your friend.
The [list of issues](https://github.com/mimblewimble/grin/issues) is a good place to start, especially the ones tagged as "help wanted" (but don't let that stop you from looking at others). If you're looking for additional ideas, the code includes `TODO` comments for minor to major improvements. Use _Search in files_ in your code editor, or `grep "TODO" -r --exclude-dir=target --exclude-dir=.git .`.
Additional tests are rewarded with an immense amount of positive karma.
@ -10,14 +10,31 @@ More documentation or updates/fixes to existing documentation are also very welc
# Find Us
If any help is needed during your effort to contribute on this project, please don't hesitate to contact us:
* Chat: [Gitter](https://gitter.im/grin_community/Lobby).
* [Forum](https://www.grin-forum.org/)
* [Website](https://grin-tech.org)
* Mailing list: join the [~MimbleWimble team](https://launchpad.net/~mimblewimble) and subscribe on Launchpad.
* News:
* Twitter for the Grin council: [@grincouncil](https://twitter.com/grincouncil)
* Twitter bot that scrapes headlines, mailing list, and reddit posts related to MimbleWinble/Grin: [@grinmw](https://twitter.com/grinmw)
When you are starting to contribute to grin, we really would appreciate if you come by the gitter chat channels.
In case of problems with trying out grin, before starting to contribute, there's the [Support chat](https://gitter.im/grin_community/support). Write there about what you've done, what you want to do, and maybe paste logs through a text paste webservice.
* Please [join the grin Lobby](https://gitter.im/grin_community/Lobby) to get a feeling for the community.
* And [see the developers chat](https://gitter.im/grin_community/dev) if you have questions about source code files.
If you explain what you're looking at and what you want to do, we'll try to help you along the way.
* Also see `docs/*.md` and the folder structure explanations, and [the wiki](https://github.com/mimblewimble/docs/wiki).
* Further information and discussions are in the [Forum](https://www.grin-forum.org/), the [website](https://grin-tech.org), the [mailing list](https://lists.launchpad.net/mimblewimble/) and news channels like the [@grincouncil](https://twitter.com/grincouncil) and a (mostly unfiltered!) Twitter bot that collects headlines, mailing list posts, and reddit posts related to MimbleWinble/Grin: [@grinmw](https://twitter.com/grinmw)
## Testing
Run all tests with `cargo test --all` and please remember to test locally before creating a PR on github.
### Check Travis output
After creating a PR on github, the code will be tested automatically by Travis CI, and from the results you'll get a red or green light. The test can take a while, and you'll have a "yellow traffic light" on your PR until Travis CI is done testing.
### Building quality
The most important thing you can do alongside - or even before - changing code, is adding tests for how grin should and should not work. See the various `tests` folders and derive test that are already there in grin.
After that, if you want to raise code quality another level, you can use `cargo check`, `cargo cov test` and `cargo tarpaulin`. Install them with `cargo install cargo-check cargo-cov; RUSTFLAGS="--cfg procmacro2_semver_exempt" cargo install cargo-tarpaulin`. Run with `cargo cov test` and `cargo tarpaulin`. The quality check tools are often integrated with `rustc` and as a side-effect only activated when some code is compiled. Because of this, if you want a complete check you'll need to `cargo clean` first.
We have some details on [code coverage and historical numbers on the wiki](https://github.com/mimblewimble/docs/wiki/Code-coverage-and-metrics).
# Pull-Request Title Prefix
@ -37,54 +54,51 @@ For example: `fix: a panick on xxx when grin exiting`. Please don't worry if you
# Grin Style Guide
Grin uses `rustfmt` to maintain consistent formatting, and we're using the git commit hook as explained below.
This project uses `rustfmt` to maintain consistent formatting. We've made sure that rustfmt runs **automatically**, but you must install rustfmt manually first.
## Install rustfmt
You should use rustup. See [build docs](doc/build.md) for more info.
**Note**: To work with grin you must use `rustup`. Linux package managers typically carry a too old rust version.
See [build docs](doc/build.md) for more info.
First ensure you have a new enough rustfmt:
```
rustup component add rustfmt-preview
rustup update
rustup component add rustfmt
rustfmt --version
```
and verify you did get version `rustfmt 0.99.1-stable (da17b689 2018-08-04)` or newer.
and verify you did get version `rustfmt 1.0.0-stable (43206f4 2018-11-30)` or newer.
## Automatic "pre-commit hook"
Then run `cargo build` to activate a git `pre-commit` hook that automates the rustfmt usage so you don't have to worry much about it. Read on for how to make this work in your advantage.
There is a basic git [pre-commit](.hooks/pre-commit) hook in the repo, and this pre-commit hook will be **automatically** configured in this project, once you run `cargo build` for the 1st time.
## Creating git commits
Or you can config it manually with the following command without building, and check it:
```
git config core.hooksPath ./.hooks
git config --list | grep hook
```
The output will be:
```
core.hookspath=./.hooks
```
When you make a commit, rustfmt will be run and we also **automatically** reformat the .rs files that your commit is touching.
Please separate the rustfmt changes into one (or several) separate commits. This is best practice.
Easiest is to make your commit as normal and if rustfmt stops you, just redo the commit again, since it should always be allowed on the second try. Then add all rustfmt:ed files (`git add -u`) and commit them (`git commit -m "rustfmt"`).
You do have to remember to do this manually.
**Note**: The pre-commit hook will not prevent commits if style issues are present, instead it will indicate any files that need formatting, and it will automatically run `rustfmt` on your changed files, each time when you try to do `git commit`.
## Running rustfmt manually
### Manually configuring git hooks
You can run rustfmt (i.e. rustfmt-preview) on one file or on all files.
If you are developing new or changed git hooks, or are curious, you can config hooks manually like this `git config core.hooksPath ./.hooks` and to verify the effect do `git config --list | grep hook` and expect the output to be `core.hookspath=./.hooks`
For example:
```
rustfmt client.rs
```
### Running rustfmt manually
Not recommended, but you can run rustfmt on a file like this: `rustfmt client.rs`
**Notes**:
1. *Please add the rustfmt corrections as a separate commit at the end of your Pull Request to make the reviewers happy.*
1. *Please keep rustfmt corrections in a separate commit. This is best practice and makes reviewing and merging your contribution work better.*
2. *If you're still not sure about what should do on the format, please feel free to ignore it. Since `rustfmt` is just a tool to make your code having pretty formatting, your changed code is definitely more important than the format. Hope you're happy to contribute on this open source project!*
2. *If unsure about code formatting, it's just fine if you ignore and discard any rustfmt changes. It's only a nice-to-have. Your contribution and code changes is the priority here. Hope you're happy to contribute on this open source project!*
3. And anyway please don't use ~~`cargo +nightly fmt`~~ if at all possible.
3. Please don't ~~`cargo +nightly fmt`~~ because all grin developers are using stable rustfmt. Also please don't rustfmt files that your code changes does not touch to avoid causing merge conflicts.
## Thanks for any contribution
Even one word correction are welcome! Our objective is to encourage you to get interested in Grin and contribute in any way possible. Thanks for any help!