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

.github/ISSUE_TEMPLATE/bug-report.md

@@ -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.)

.github/ISSUE_TEMPLATE/config.yml

@@ -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

.github/ISSUE_TEMPLATE/feature-request.md

@@ -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.*

.github/ISSUE_TEMPLATE/question.md

@@ -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.*

CONTRIBUTING.md

@@ -3,39 +3,37 @@ sections on how to contribute code and bug reports.
 
 ### 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
 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,
 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
-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 small and clean pull requests that are easy to review but make sure they
   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)
   to verify your code passes before pushing to save time.
 * This project has a strong focus on providing general solutions using a
   minimal amount of code, thus small pull requests are greatly preferred.
 
-[pre-commit]: https://pre-commit.com
-
 ### Licensing of contributions
 
 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
 other computer software, distribute, and sublicense such enhancements or
 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 don’t 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

ISSUE_TEMPLATE.md

@@ -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.)

LICENSE

@@ -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
 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.

tests/CMakeLists.txt

@@ -84,7 +84,7 @@ set(PYBIND11_TEST_FILES
     test_virtual_functions.cpp)
 
 # 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:
 #     cmake -DPYBIND11_TEST_OVERRIDE= ..
 if(PYBIND11_TEST_OVERRIDE)