docs: contrib/issue templates (#2377)

* docs: move helpers to .github where allowed

* docs: more guidelines in CONTRIBUTING

* chore: update issue templates

* fix: review from @bstaletic

* refactor: a few points from @rwgk

* docs: more touchup, review changes
This commit is contained in:
Henry Schreiner 2020-08-17 10:14:23 -04:00 committed by GitHub
parent 4d9024ec71
commit 6404099712
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 204 additions and 36 deletions

28
.github/ISSUE_TEMPLATE/bug-report.md vendored Normal file
View File

@ -0,0 +1,28 @@
---
name: Bug Report
about: File an issue about a bug
title: "[BUG] "
---
Make sure you've completed the following steps before submitting your issue -- thank you!
1. Make sure you've read the [documentation][]. Your issue may be addressed there.
2. Search the [issue tracker][] to verify that this hasn't already been reported. +1 or comment there if it has.
3. Consider asking first in the [Gitter chat room][].
4. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible.
a. If possible, make a PR with a new, failing test to give us a starting point to work on!
[documentation]: https://pybind11.readthedocs.io
[issue tracker]: https://github.com/pybind/pybind11/issues
[Gitter chat room]: https://gitter.im/pybind/Lobby
*After reading, remove this checklist and the template text in parentheses below.*
## Issue description
(Provide a short description, state the expected behavior and what actually happens.)
## Reproducible example code
(The code should be minimal, have no external dependencies, isolate the function(s) that cause breakage. Submit matched and complete C++ and Python snippets that can be easily compiled and run to diagnose the issue.)

5
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View File

@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Gitter room
url: https://gitter.im/pybind/Lobby
about: A room for discussing pybind11 with an active community

View File

@ -0,0 +1,16 @@
---
name: Feature Request
about: File an issue about adding a feature
title: "[FEAT] "
---
Make sure you've completed the following steps before submitting your issue -- thank you!
1. Check if your feature has already been mentioned / rejected / planned in other issues.
2. If those resources didn't help, consider asking in the [Gitter chat room][] to see if this is interesting / useful to a larger audience and possible to implement reasonably,
4. If you have a useful feature that passes the previous items (or not suitable for chat), please fill in the details below.
[Gitter chat room]: https://gitter.im/pybind/Lobby
*After reading, remove this checklist.*

21
.github/ISSUE_TEMPLATE/question.md vendored Normal file
View File

@ -0,0 +1,21 @@
---
name: Question
about: File an issue about unexplained behavior
title: "[QUESTION] "
---
If you have a question, please check the following first:
1. Check if your question has already been answered in the [FAQ][] section.
2. Make sure you've read the [documentation][]. Your issue may be addressed there.
3. If those resources didn't help and you only have a short question (not a bug report), consider asking in the [Gitter chat room][]
4. Search the [issue tracker][], including the closed issues, to see if your question has already been asked/answered. +1 or comment if it has been asked but has no answer.
5. If you have a more complex question which is not answered in the previous items (or not suitable for chat), please fill in the details below.
6. Include a self-contained and minimal piece of code that illustrates your question. If that's not possible, try to make the description as clear as possible.
[FAQ]: http://pybind11.readthedocs.io/en/latest/faq.html
[documentation]: https://pybind11.readthedocs.io
[issue tracker]: https://github.com/pybind/pybind11/issues
[Gitter chat room]: https://gitter.im/pybind/Lobby
*After reading, remove this checklist.*

View File

@ -3,39 +3,37 @@ sections on how to contribute code and bug reports.
### Reporting bugs ### Reporting bugs
At the moment, this project is run in the spare time of a single person Before submitting a question or bug report, please take a moment of your time
([Wenzel Jakob](http://rgl.epfl.ch/people/wjakob)) with very limited resources and ensure that your issue isn't already discussed in the project documentation
for issue tracker tickets. Thus, before submitting a question or bug report, provided at [pybind11.readthedocs.org][] or in the [issue tracker][]. You can
please take a moment of your time and ensure that your issue isn't already also check [gitter][] to see if it came up before.
discussed in the project documentation provided at
[http://pybind11.readthedocs.org/en/latest](http://pybind11.readthedocs.org/en/latest).
Assuming that you have identified a previously unknown problem or an important Assuming that you have identified a previously unknown problem or an important
question, it's essential that you submit a self-contained and minimal piece of question, it's essential that you submit a self-contained and minimal piece of
code that reproduces the problem. In other words: no external dependencies, code that reproduces the problem. In other words: no external dependencies,
isolate the function(s) that cause breakage, submit matched and complete C++ isolate the function(s) that cause breakage, submit matched and complete C++
and Python snippets that can be easily compiled and run on my end. and Python snippets that can be easily compiled and run in isolation; or
ideally make a small PR with a failing test case that can be used as a starting
point.
## Pull requests ## Pull requests
Contributions are submitted, reviewed, and accepted using Github pull requests.
Please refer to [this Contributions are submitted, reviewed, and accepted using GitHub pull requests.
article](https://help.github.com/articles/using-pull-requests) for details and Please refer to [this article][using pull requests] for details and adhere to
adhere to the following rules to make the process as smooth as possible: the following rules to make the process as smooth as possible:
* Make a new branch for every feature you're working on. * Make a new branch for every feature you're working on.
* Make small and clean pull requests that are easy to review but make sure they * Make small and clean pull requests that are easy to review but make sure they
do add value by themselves. do add value by themselves.
* Add tests for any new functionality and run the test suite (``make pytest``) * Add tests for any new functionality and run the test suite (`cmake --build
to ensure that no existing features break. build --target pytest`) to ensure that no existing features break.
* Please run [``pre-commit``][pre-commit] to check your code matches the * Please run [`pre-commit`][pre-commit] to check your code matches the
project style. (Note that ``gawk`` is required.) Use `pre-commit run project style. (Note that `gawk` is required.) Use `pre-commit run
--all-files` before committing (or use installed-mode, check pre-commit docs) --all-files` before committing (or use installed-mode, check pre-commit docs)
to verify your code passes before pushing to save time. to verify your code passes before pushing to save time.
* This project has a strong focus on providing general solutions using a * This project has a strong focus on providing general solutions using a
minimal amount of code, thus small pull requests are greatly preferred. minimal amount of code, thus small pull requests are greatly preferred.
[pre-commit]: https://pre-commit.com
### Licensing of contributions ### Licensing of contributions
pybind11 is provided under a BSD-style license that can be found in the pybind11 is provided under a BSD-style license that can be found in the
@ -51,3 +49,120 @@ hereby grant the following license: a non-exclusive, royalty-free perpetual
license to install, use, modify, prepare derivative works, incorporate into license to install, use, modify, prepare derivative works, incorporate into
other computer software, distribute, and sublicense such enhancements or other computer software, distribute, and sublicense such enhancements or
derivative works thereof, in binary and source code form. derivative works thereof, in binary and source code form.
## Development of pybind11
To setup an ideal development environment, run the following commands on a
system with CMake 3.14+:
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r tests/requirements.txt
cmake -S . -B build -DPYTHON_EXECUTABLE=$(which python) -DDOWNLOAD_CATCH=ON -DDOWNLOAD_EIGEN=ON
cmake --build build -j4
```
Tips:
* You can use `virtualenv` (from PyPI) instead of `venv` (which is Python 3
only).
* You can select any name for your environment folder; if it contains "env" it
will be ignored by git.
* If you dont have CMake 3.14+, just add “cmake” to the pip install command.
* You can use `-DPYBIND11_FINDPYTHON=ON` instead of setting the
`PYTHON_EXECUTABLE` - the new search algorithm can find virtual environments,
Conda, and more.
### Configuration options
In CMake, configuration options are given with “-D”. Options are stored in the
build directory, in the `CMakeCache.txt` file, so they are remembered for each
build directory. Two selections are special - the generator, given with `-G`,
and the compiler, which is selected based on environment variables `CXX` and
similar, or `-DCMAKE_CXX_COMPILER=`. Unlike the others, these cannot be changed
after the initial run.
The valid options are:
* `-DCMAKE_BUILD_TYPE`: Release, Debug, MinSizeRel, RelWithDebInfo
* `-DPYBIND11_FINDPYTHON=ON`: Use CMake 3.12+s FindPython instead of the
classic, deprecated, custom FindPythonLibs
* `-DPYBIND11_NOPYTHON=ON`: Disable all Python searching (disables tests)
* `-DBUILD_TESTING=ON`: Enable the tests
* `-DDOWNLOAD_CATCH=ON`: Download catch to build the C++ tests
* `-DOWNLOAD_EIGEN=ON`: Download Eigen for the NumPy tests
* `-DPYBIND11_INSTALL=ON/OFF`: Enable the install target (on by default for the
master project)
* `-DUSE_PYTHON_INSTALL_DIR=ON`: Try to install into the python dir
<details><summary>A few standard CMake tricks: (click to expand)</summary><p>
* Use `cmake --build build -v` to see the commands used to build the files.
* Use `cmake build -LH` to list the CMake options with help.
* Use `ccmake` if available to see a curses (terminal) gui, or `cmake-gui` for
a completely graphical interface (not present in the PyPI package).
* Use `-G` and the name of a generator to use something different, like `Ninja`
(automatic multithreading!). `cmake --help` lists the generators available.
* Open the `CMakeLists.txt` with QtCreator to generate for that IDE.
* Use `cmake --build build -j12` to build with 12 cores (for example).
* You can use `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` to generate the `.json` file
that some tools expect.
</p></details>
To run the tests, you can "build" the check target:
```bash
cmake --build build --target check
```
`--target` can be spelled `-t` in CMake 3.15+. You can also run individual
tests with these targets:
* `pytest`: Python tests only
* `cpptest`: C++ tests only
* `test_cmake_build`: Install / subdirectory tests
If you want to build just a subset of tests, use
`-DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_pickling.cpp"`. If this is
empty, all tests will be built.
### Formatting
All formatting is handled by pre-commit.
Install with brew (macOS) or pip (any OS):
```bash
# Any OS
python3 -m pip install pre-commit
# OR macOS with homebrew:
brew install pre-commit
```
Then, you can run it on the items you've added to your staging area, or all
files:
```bash
pre-commit run
# OR
pre-commit run --all-files
```
And, if you want to always use it, you can install it as a git hook (hence the
name, pre-commit):
```bash
pre-commit install
```
[pre-commit]: https://pre-commit.com
[pybind11.readthedocs.org]: http://pybind11.readthedocs.org/en/latest
[issue tracker]: https://github.com/pybind/pybind11/issues
[gitter]: https://gitter.im/pybind/Lobby
[using pull requests]: https://help.github.com/articles/using-pull-requests

View File

@ -1,17 +0,0 @@
Make sure you've completed the following steps before submitting your issue -- thank you!
1. Check if your question has already been answered in the [FAQ](http://pybind11.readthedocs.io/en/latest/faq.html) section.
2. Make sure you've read the [documentation](http://pybind11.readthedocs.io/en/latest/). Your issue may be addressed there.
3. If those resources didn't help and you only have a short question (not a bug report), consider asking in the [Gitter chat room](https://gitter.im/pybind/Lobby).
4. If you have a genuine bug report or a more complex question which is not answered in the previous items (or not suitable for chat), please fill in the details below.
5. Include a self-contained and minimal piece of code that reproduces the problem. If that's not possible, try to make the description as clear as possible.
*After reading, remove this checklist and the template text in parentheses below.*
## Issue description
(Provide a short description, state the expected behavior and what actually happens.)
## Reproducible example code
(The code should be minimal, have no external dependencies, isolate the function(s) that cause breakage. Submit matched and complete C++ and Python snippets that can be easily compiled and run to diagnose the issue.)

View File

@ -25,5 +25,5 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Please also refer to the file CONTRIBUTING.md, which clarifies licensing of Please also refer to the file .github/CONTRIBUTING.md, which clarifies licensing of
external contributions to this project including patches, pull requests, etc. external contributions to this project including patches, pull requests, etc.

View File

@ -84,7 +84,7 @@ set(PYBIND11_TEST_FILES
test_virtual_functions.cpp) test_virtual_functions.cpp)
# Invoking cmake with something like: # Invoking cmake with something like:
# cmake -DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_picking.cpp" .. # cmake -DPYBIND11_TEST_OVERRIDE="test_callbacks.cpp;test_pickling.cpp" ..
# lets you override the tests that get compiled and run. You can restore to all tests with: # lets you override the tests that get compiled and run. You can restore to all tests with:
# cmake -DPYBIND11_TEST_OVERRIDE= .. # cmake -DPYBIND11_TEST_OVERRIDE= ..
if(PYBIND11_TEST_OVERRIDE) if(PYBIND11_TEST_OVERRIDE)