github.com/gopherd/gonum@v0.0.4/CONTRIBUTING.md (about)

     1  # [<img src="https://avatars1.githubusercontent.com/u/3771091?v=3&s=30">](https://github.com/gonum) Contribution Guidelines
     2  #### Introduction
     3  
     4  The Gonum project provides general purpose numerical computing and data science libraries for the Go programming language, and we would like you to join us in improving Gonum's quality and scope.
     5  This document is for anyone who is contributing or interested in contributing.
     6  Questions about Gonum or the use of its libraries can be directed to [gonum-dev](https://groups.google.com/forum/#!forum/gonum-dev).
     7  
     8  #### Table of Contents
     9  
    10  [Project Scope](#project-scope)
    11  
    12  [The Gonum Repositories](#the-gonum-repositories)
    13  
    14  [Contributing](#Contributing)
    15    * [Working Together](#working-together)
    16    * [Reporting Bugs](#reporting-bugs)
    17    * [Suggesting Enhancements](#suggesting-enhancements)
    18    * [Your First Code Contribution](#your-first-code-contribution)
    19    * [Code Contribution](#code-contribution)
    20    * [Code Review](#code-review)
    21    * [What Can I Do to Help?](#what-can-i-do-to-help)
    22    * [Style](#style)
    23  
    24  ## Project Scope
    25  
    26  The purpose of the Gonum project is to provide general purpose numerical computing and data science libraries for the Go programming language.
    27  The libraries should aim to provide building blocks for disciplinary work and advanced algorithms.
    28  Code should be implemented in pure Go.
    29  Calls to C, Fortran, or other languages may be justified with performance considerations, but should be opt-in for users.
    30  Calls to assembly should be opt-out, if included.
    31  Code should favor readability and explicitness over cleverness.
    32  This makes code easy to review and verify, not only at submission, but also for users who want to understand how the algorithms work.
    33  Where possible, the source of algorithms should be referenced in the comments.
    34  
    35  ## The Gonum Repositories
    36  
    37  Here are the current repositories for the Gonum project.
    38  If code you want to contribute doesn't quite fit in any of them, then please start a discussion on the [mailing list](https://groups.google.com/forum/#!forum/gonum-dev).
    39  Code can be found at [github.com/gonum/](https://github.com/gonum/)\<repo\>, and documentation at godoc.org/github.com/gonum/\<repo\>.
    40  
    41  * [gonum](https://github.com/gonum/gonum) — The gonum repository contains the majority of Gonum packages
    42  * [plot](https://github.com/gonum/plot) — A repository for plotting and visualizing data
    43  * [netlib](https://github.com/gonum/netlib) — The netlib repository contains Cgo wrappers for C implementations of BLAS and LAPACKE
    44  * [hdf5](https://github.com/gonum/hdf5) — The hdf5 repository contains a Cgo wrapper for the HDF5 data storage and access library
    45  * [exp](https://github.com/gonum/exp) — The exp repository contains experimental and incomplete package implementations
    46  * [tools](https://github.com/gonum/tools) — Tools for working with Go code
    47  * [talks](https://github.com/gonum/talks) — Talks given about Go and Gonum delivered by Gonum developers
    48  * [gonum.github.io](https://github.com/gonum/gonum.github.io) — Gonum website
    49  
    50  ## Contributing
    51  
    52  ### Working Together
    53  
    54  When contributing or otherwise participating please follow the [Gonum community's conduct expectations](CONDUCT.md).
    55  
    56  ### Reporting Bugs
    57  
    58  When you encounter a bug, please open an issue on the corresponding repository.
    59  Start the issue title with the repository/sub-repository name, like `stat/distmv: issue name`.
    60  Be specific about the environment you encountered the bug in.
    61  If you are able to write a test that reproduces the bug, please include it in the issue.
    62  As a rule we keep all tests OK.
    63  
    64  ### Suggesting Enhancements
    65  
    66  If the scope of the enhancement is small, open an issue.
    67  If it is large, such as suggesting a new repository, sub-repository, or interface refactoring, then please start a discussion on [the gonum-dev list](https://groups.google.com/forum/#!forum/gonum-dev).
    68  
    69  ### Your First Code Contribution
    70  
    71  If you are a new contributor, thank you! Before your first merge, you will need to be added to the [CONTRIBUTORS](https://github.com/gonum/gonum/blob/master/CONTRIBUTORS) and [AUTHORS](https://github.com/gonum/gonum/blob/master/AUTHORS) file; after your contribution has been accepted you will be asked to open a pull request adding yourself to them.
    72  All Gonum code follows the BSD license in the [license document](https://github.com/gonum/gonum/blob/master/LICENSE).
    73  We prefer that code contributions do not come with additional licensing.
    74  For exceptions, added code must also follow a BSD license.
    75  
    76  ### Code Contribution
    77  
    78  If it is possible to split a large pull request into two or more smaller pull requests, please try to do so.
    79  Pull requests should include tests for any new code before merging.
    80  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.
    81  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.
    82  When tests use magic numbers, please include a comment explaining the source of the number.
    83  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).
    84  
    85  ### Code Review
    86  
    87  If you are a contributor, please be welcoming to new contributors.  [Here](https://sage.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) is a good guide.
    88  
    89  There are several terms code reviews may use that you should become familiar with.
    90  
    91    * ` LGTM ` — looks good to me
    92    * ` SGTM ` — sounds good to me
    93    * ` s/foo/bar/ ` — please replace ` foo ` with ` bar `; this is [sed syntax](http://en.wikipedia.org/wiki/Sed#Usage)
    94    * ` s/foo/bar/g ` — please replace ` foo ` with ` bar ` throughout your entire change
    95  
    96  We follow the convention of requiring at least 1 reviewer to say LGTM before a merge.
    97  When code is tricky or controversial, submitters and reviewers can request additional review from others and more LGTMs before merge.
    98  You can ask for more review by saying PTAL in a comment in a pull request.
    99  You can follow a PTAL with one or more @someone to get the attention of particular people.
   100  If you don't know who to ask, and aren't getting enough review after saying PTAL, then PTAL @gonum/developers will get more attention.
   101  Also note that you do not have to be the pull request submitter to request additional review.
   102  
   103  ### What Can I Do to Help?
   104  
   105  If you are looking for some way to help the Gonum project, there are good places to start, depending on what you are comfortable with.
   106  You can [search](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Agonum) for open issues in need of resolution.
   107  You can improve documentation, or improve examples.
   108  You can add and improve tests.
   109  You can improve performance, either by improving accuracy, speed, or both.
   110  You can suggest and implement new features that you think belong in Gonum.
   111  
   112  ### Style
   113  
   114  We use [Go style](https://github.com/golang/go/wiki/CodeReviewComments).