|
| 1 | +# Contributing |
| 2 | + |
| 3 | +The `go-python` project (and `gpython`) eagerly accepts contributions from the community. |
| 4 | + |
| 5 | +## Introduction |
| 6 | + |
| 7 | + |
| 8 | +The `go-python` project provides libraries and tools in Go for the Go community to better integrate with Python projects and libraries, and we would like you to join us in improving `go-python`'s quality and scope. |
| 9 | +This document is for contributors or those interested in contributing. |
| 10 | +Questions about `go-python` and the use of its libraries can be directed to the [go-python ](mailto:[email protected]) mailing list. |
| 11 | + |
| 12 | +## Contributing |
| 13 | + |
| 14 | +### Working Together |
| 15 | + |
| 16 | +When contributing or otherwise participating, please: |
| 17 | + |
| 18 | +- Be friendly and welcoming |
| 19 | +- Be patient |
| 20 | +- Be thoughtful |
| 21 | +- Be respectful |
| 22 | +- Be charitable |
| 23 | +- Avoid destructive behavior |
| 24 | + |
| 25 | +Excerpted from the [Go conduct document](https://golang.org/conduct). |
| 26 | + |
| 27 | +### Reporting Bugs |
| 28 | + |
| 29 | +When you encounter a bug, please open an issue on the corresponding repository. |
| 30 | +Start the issue title with the repository/sub-repository name, like `bind: issue name`. |
| 31 | +Be specific about the environment you encountered the bug in (_e.g.:_ operating system, Go compiler version, ...). |
| 32 | +If you are able to write a reproducer for the bug, please include it in the issue. |
| 33 | +As a rule, we keep all tests OK and try to increase code coverage. |
| 34 | + |
| 35 | +### Suggesting Enhancements |
| 36 | + |
| 37 | +If the scope of the enhancement is small, open an issue. |
| 38 | +If it is large, such as suggesting a new repository, sub-repository, or interface refactoring, then please start a discussion on [the go-python list](https://groups.google.com/forum/#!forum/go-python). |
| 39 | + |
| 40 | +### Your First Code Contribution |
| 41 | + |
| 42 | +If you are a new contributor, *thank you!* |
| 43 | +Before your first merge, you will need to be added to the [CONTRIBUTORS](https://github.com/go-python/license/blob/master/CONTRIBUTORS) and [AUTHORS](https://github.com/go-python/license/blob/master/AUTHORS) files. |
| 44 | +Open a pull request adding yourself to these files. |
| 45 | +All `go-python` code follows the BSD license in the [license document](https://github.com/go-python/license/blob/master/LICENSE). |
| 46 | +We prefer that code contributions do not come with additional licensing. |
| 47 | +For exceptions, added code must also follow a BSD license. |
| 48 | + |
| 49 | +### Code Contribution |
| 50 | + |
| 51 | +If it is possible to split a large pull request into two or more smaller pull requests, please try to do so. |
| 52 | +Pull requests should include tests for any new code before merging. |
| 53 | +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. |
| 54 | +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. |
| 55 | +When tests use magic numbers, please include a comment explaining the source of the number. |
| 56 | +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://godoc.org/golang.org/x/perf/cmd/benchstat). |
| 57 | + |
| 58 | +Commit messages also follow some rules. |
| 59 | +They are best explained at the official [Go](https://golang.org) "Contributing guidelines" document: |
| 60 | + |
| 61 | +[golang.org/doc/contribute.html](https://golang.org/doc/contribute.html#commit_changes) |
| 62 | + |
| 63 | +For example: |
| 64 | + |
| 65 | +``` |
| 66 | +bind: add support for cffi |
| 67 | +
|
| 68 | +This CL adds support for the cffi python backend. |
| 69 | +The existing implementation, cpython, only generates code for the |
| 70 | +CPython-2 C API. |
| 71 | +Now, with cffi, we support generation of python modules for Python-2, |
| 72 | +Python-3 and PyPy VMs. |
| 73 | +
|
| 74 | +Fixes go-python/gpython#42. |
| 75 | +``` |
| 76 | + |
| 77 | +If the `CL` modifies multiple packages at the same time, include them in the commit message: |
| 78 | + |
| 79 | +``` |
| 80 | +py,bind: implement wrapping of Go interfaces |
| 81 | +
|
| 82 | +bla-bla |
| 83 | +
|
| 84 | +Fixes go-python/gpython#40. |
| 85 | +``` |
| 86 | + |
| 87 | +Please always format your code with [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports). |
| 88 | +Best is to have it invoked as a hook when you save your `.go` files. |
| 89 | + |
| 90 | +Files in the `go-python` repository don't list author names, both to avoid clutter and to avoid having to keep the lists up to date. |
| 91 | +Instead, your name will appear in the change log and in the [CONTRIBUTORS](https://github.com/go-python/license/blob/master/CONTRIBUTORS) and [AUTHORS](https://github.com/go-python/license/blob/master/AUTHORS) files. |
| 92 | + |
| 93 | +New files that you contribute should use the standard copyright header: |
| 94 | + |
| 95 | +``` |
| 96 | +// Copyright 20xx The go-python Authors. All rights reserved. |
| 97 | +// Use of this source code is governed by a BSD-style |
| 98 | +// license that can be found in the LICENSE file. |
| 99 | +``` |
| 100 | + |
| 101 | +Files in the repository are copyright the year they are added. |
| 102 | +Do not update the copyright year on files that you change. |
| 103 | + |
| 104 | +### Code Review |
| 105 | + |
| 106 | +If you are a contributor, please be welcoming to new contributors. |
| 107 | +[Here](http://sarah.thesharps.us/2014/09/01/the-gentle-art-of-patch-review/) is a good guide. |
| 108 | + |
| 109 | +There are several terms code reviewers may use that you should become familiar with. |
| 110 | + |
| 111 | + * ` LGTM ` — looks good to me |
| 112 | + * ` SGTM ` — sounds good to me |
| 113 | + * ` PTAL ` — please take another look |
| 114 | + * ` CL ` — change list; a single commit in the repository |
| 115 | + * ` s/foo/bar/ ` — please replace ` foo ` with ` bar `; this is [sed syntax](http://en.wikipedia.org/wiki/Sed#Usage) |
| 116 | + * ` s/foo/bar/g ` — please replace ` foo ` with ` bar ` throughout your entire change |
| 117 | + |
| 118 | +We follow the convention of requiring at least 1 reviewer to say LGTM before a merge. |
| 119 | +When code is tricky or controversial, submitters and reviewers can request additional review from others and more LGTMs before merge. |
| 120 | +You can ask for more review by saying PTAL in a comment in a pull request. |
| 121 | +You can follow a PTAL with one or more @someone to get the attention of particular people. |
| 122 | +If you don't know who to ask, and aren't getting enough review after saying PTAL, then PTAL @go-python/developers will get more attention. |
| 123 | +Also note that you do not have to be the pull request submitter to request additional review. |
| 124 | + |
| 125 | +### What Can I Do to Help? |
| 126 | + |
| 127 | +If you are looking for some way to help the `go-python` project, there are good places to start, depending on what you are comfortable with. |
| 128 | + |
| 129 | +- You can [search](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Ago-python) for open issues in need of resolution. |
| 130 | +- You can improve documentation, or improve examples. |
| 131 | +- You can add and improve tests. |
| 132 | +- You can improve performance, either by improving accuracy, speed, or both. |
| 133 | +- You can suggest and implement new features that you think belong in `go-python`. |
| 134 | + |
| 135 | +### Style |
| 136 | + |
| 137 | +We use [Go style](https://github.com/golang/go/wiki/CodeReviewComments). |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +This _"Contributing"_ guide has been extracted from the [Gonum](https://gonum.org) project. |
| 142 | +Its guide is [here](https://github.com/gonum/license/blob/master/CONTRIBUTING.md). |
0 commit comments