|
| 1 | +# Contribution Guidelines |
| 2 | +#### Introduction |
| 3 | + |
| 4 | +The sklearn project provides a partial port of the scikit-learn libraries for the Go programming language, and we would like you to join us in improving sklearn's quality and scope. |
| 5 | +This document is for anyone who is contributing or interested in contributing. |
| 6 | +Questions about sklearn or the use of its libraries can be directed to [golang-sklearn](https://groups.google.com/forum/#!forum/golang-sklearn). |
| 7 | + |
| 8 | +#### Table of Contents |
| 9 | + |
| 10 | +[Project Scope](#project-scope) |
| 11 | + |
| 12 | +[Contributing](#Contributing) |
| 13 | + * [Working Together](#working-together) |
| 14 | + * [Reporting Bugs](#reporting-bugs) |
| 15 | + * [Suggesting Enhancements](#suggesting-enhancements) |
| 16 | + * [Your First Code Contribution](#your-first-code-contribution) |
| 17 | + * [Code Contribution](#code-contribution) |
| 18 | + * [Code Review](#code-review) |
| 19 | + * [What Can I Do to Help?](#what-can-i-do-to-help) |
| 20 | + * [Style](#style) |
| 21 | + |
| 22 | +## Project Scope |
| 23 | + |
| 24 | +The purpose of the sklearn project is to provide a partial port of the scikit-learn libraries for the Go programming language. |
| 25 | +The libraries should aim to provide building blocks for disciplinary work and advanced algorithms. |
| 26 | +Code should be implemented in pure Go. |
| 27 | +Calls to C, Fortran, or other languages may be justified with performance considerations, but should be opt-in for users. |
| 28 | +Calls to assembly should be opt-out, if included. |
| 29 | +Code should favor readability and explicitness over cleverness. |
| 30 | +This makes code easy to review and verify, not only at submission, but also for users who want to understand how the algorithms work. |
| 31 | +Where possible, the source of algorithms should be referenced in the comments. |
| 32 | + |
| 33 | +## Contributing |
| 34 | + |
| 35 | +### Working Together |
| 36 | + |
| 37 | +When contributing or otherwise participating, please: |
| 38 | + |
| 39 | +- Be friendly and welcoming |
| 40 | +- Be patient |
| 41 | +- Be thoughtful |
| 42 | +- Be respectful |
| 43 | +- Be charitable |
| 44 | +- Avoid destructive behavior |
| 45 | + |
| 46 | +Excerpted from the [Go conduct document](https://golang.org/conduct). |
| 47 | + |
| 48 | +### Reporting Bugs |
| 49 | + |
| 50 | +When you encounter a bug, please open an issue. |
| 51 | +Start the issue title with the repository/sub-repository name, like `metrics: issue name`. |
| 52 | +Be specific about the environment you encountered the bug in. |
| 53 | +If you are able to write a test that reproduces the bug, please include it in the issue. |
| 54 | +As a rule we keep all tests OK. |
| 55 | + |
| 56 | +### Suggesting Enhancements |
| 57 | + |
| 58 | +If the scope of the enhancement is small, open PR. |
| 59 | +If it is large, such as suggesting a new repository, sub-repository, or interface refactoring, then please start a discussion on [the golang-sklearn list](https://groups.google.com/forum/#!forum/golang-sklearn). |
| 60 | + |
| 61 | +### Your First Code Contribution |
| 62 | + |
| 63 | +If you are a new contributor, thank you! Before your first merge, you will need to be added to the [CONTRIBUTORS](https://github.com/pa-m/sklearn/blob/master/CONTRIBUTORS) and [AUTHORS](https://github.com/pa-m/sklearn/blob/master/AUTHORS) file. |
| 64 | +Open a pull request adding yourself to them. |
| 65 | +All sklearn code follows the MIT license in the [license document](https://github.com/pa-m/sklearn/blob/master/LICENSE). |
| 66 | +We prefer that code contributions do not come with additional licensing. |
| 67 | +For exceptions, added code must also follow a MIT license. |
| 68 | + |
| 69 | +### Code Contribution |
| 70 | + |
| 71 | +If it is possible to split a large pull request into two or more smaller pull requests, please try to do so. |
| 72 | +Pull requests should include tests for any new code before merging. |
| 73 | +It is ok to start a pull request on partially implemented code to get feedback, and see if your approach to a problem is sound. |
| 74 | +You don't need to have tests, or even have code that compiles to open a pull request, although both will be needed before merge. |
| 75 | +When tests use magic numbers, please include a comment explaining the source of the number. |
| 76 | +Benchmarks are optional for new features, but if you are submitting a pull request justified by performance improvement, you will need benchmarks to measure the impact of your change, and the pull request should include a report from [benchcmp](https://godoc.org/golang.org/x/tools/cmd/benchcmp) or, preferably, [benchstat](https://github.com/rsc/benchstat). |
| 77 | + |
| 78 | +### Code Review |
| 79 | + |
| 80 | +If you are a contributor, please be welcoming to new contributors. [Here](http://sarah.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) is a good guide. |
| 81 | + |
| 82 | +There are several terms code reviews may use that you should become familiar with. |
| 83 | + |
| 84 | + * ` LGTM ` — looks good to me |
| 85 | + * ` SGTM ` — sounds good to me |
| 86 | + * ` s/foo/bar/ ` — please replace ` foo ` with ` bar `; this is [sed syntax](http://en.wikipedia.org/wiki/Sed#Usage) |
| 87 | + * ` s/foo/bar/g ` — please replace ` foo ` with ` bar ` throughout your entire change |
| 88 | + |
| 89 | +We follow the convention of requiring at least 1 reviewer to say LGTM before a merge. |
| 90 | +When code is tricky or controversial, submitters and reviewers can request additional review from others and more LGTMs before merge. |
| 91 | +You can ask for more review by saying PTAL in a comment in a pull request. |
| 92 | +You can follow a PTAL with one or more @someone to get the attention of particular people. |
| 93 | +Also note that you do not have to be the pull request submitter to request additional review. |
| 94 | + |
| 95 | +### What Can I Do to Help? |
| 96 | + |
| 97 | +If you are looking for some way to help the sklearn project, there are good places to start, depending on what you are comfortable with. |
| 98 | +You can [search](https://github.com/pa-m/sklearn/issues) for open issues in need of resolution. |
| 99 | +You can improve documentation, or improve examples. |
| 100 | +You can add and improve tests. |
| 101 | +You can improve performance, either by improving accuracy, speed, or both. |
| 102 | +You can suggest and implement new features that you think belong in sklearn. |
| 103 | + |
| 104 | +### Style |
| 105 | + |
| 106 | +We use [Go style](https://github.com/golang/go/wiki/CodeReviewComments). |
0 commit comments