Documentation work

.github/CONTRIBUTING.md

@@ -1,35 +1,86 @@
 # Contribution Guide
 
-This file is a work in progress and you can report errors or submit patches for
+## Contents
-it the same as any other file.
+
+- [Reporting a bug](#reporting-a-bug)
+    - [Reporting a compile or link bug](#reporting-a-compile-or-link-bug)
+    - [Reporting a segfault or other crash bug](#reporting-a-segfault-or-other-crash-bug)
+    - [Reporting a context creation bug](#reporting-a-context-creation-bug)
+    - [Reporting a monitor or video mode bug](#reporting-a-monitor-or-video-mode-bug)
+    - [Reporting an input or event bug](#reporting-an-input-or-event-bug)
+    - [Reporting some other library bug](#reporting-some-other-library-bug)
+    - [Reporting a documentation bug](#reporting-a-documentation-bug)
+    - [Reporting a website bug](#reporting-a-website-bug)
+- [Requesting a feature](#requesting-a-feature)
+- [Contributing a bug fix](#contributing-a-bug-fix)
+- [Contributing a feature](#contributing-a-feature)
 
 
 ## Reporting a bug
 
-If GLFW is behaving unexpectedly, make sure you have set an error callback.
+If GLFW is behaving unexpectedly at run-time, start by setting an [error
-GLFW will often tell you the cause of an issue via this callback.
+callback](http://www.glfw.org/docs/latest/intro_guide.html#error_handling).
+GLFW will often tell you the cause of an error via this callback.  If it
+doesn't, that might be a separate bug.
 
 If GLFW is crashing or triggering asserts, make sure that all your object
 handles and other pointers are valid.
 
+There are issue labels for both platforms and GPU manufacturers, so there is no
+need to mention these in the subject line.  If you do, it will be removed when
+the issue is labeled.
+
+
+### Reporting a compile or link bug
+
+__Note:__ GLFW needs many system APIs to do its job, which on some platforms
+means linking to many system libraries.  If you are using GLFW as a static
+library, that means your application needs to link to these in addition to GLFW.
+See the [Build guide](http://www.glfw.org/docs/latest/build.html) for more
+information.
+
+Always include the __operating system name and version__ (i.e. `Windows
+7 64-bit` or `Ubuntu 15.10`) and the __compiler name and version__ (i.e. `Visual
+C++ 2015 Update 2`).  If you are using an official release of GLFW,
+include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the
+__GLFW commit ID__ (i.e.  `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
+
+Please also include the __complete build log__ from your compiler and linker,
+even if it's long.  It can always be shortened later, if necessary.
+
+
+#### Quick template
+
+```
+OS and version:
+Compiler version:
+Release or commit:
+Build log:
+```
+
+
+### Reporting a segfault or other crash bug
+
 Always include the __operating system name and version__ (i.e. `Windows
 7 64-bit` or `Ubuntu 15.10`).  If you are using an official release of GLFW,
 include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the
 __GLFW commit ID__ (i.e.  `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
-If possible, please also include the __GLFW version string__ (`3.2.0 X11 EGL
+
-clock_gettime /dev/js XI Xf86vm`), as described
+Please also include any __error messages__ provided to your application via the
-[here](http://www.glfw.org/docs/latest/intro.html#intro_version_string).
+[error
+callback](http://www.glfw.org/docs/latest/intro_guide.html#error_handling) and
+the __full call stack__ of the crash, or if the crash does not occur in debug
+mode, mention that instead.
 
 
-### Reporting a compile or link bug
+#### Quick template
 
-__Note:__ GLFW needs many system APIs to do its job.  See the [Building
+```
-applications](http://www.glfw.org/docs/latest/build.html) guide for more
+OS and version:
-information.
+Release or commit:
-
+Error messages:
-In addition to the information above, always include the complete build log from
+Call stack:
-your compiler and linker.  Issue posts are editable so it can always be
+```
-shortened later.
 
 
 ### Reporting a context creation bug
@@ -38,23 +89,42 @@ __Note:__ Windows ships with graphics drivers that do not support OpenGL.  If
 GLFW says that your machine lacks support for OpenGL, it very likely does.
 Install drivers from the computer manufacturer or graphics card manufacturer
 ([Nvidia](http://www.geforce.com/drivers),
- [AMD](http://support.amd.com/en-us/download),
+[AMD](http://support.amd.com/en-us/download),
- [Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to
+[Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to
 fix this.
 
-__Note:__ AMD only supports OpenGL ES on Windows via EGL.  EGL support is not
+__Note:__ AMD only supports OpenGL ES on Windows via EGL.  See the
-enabled in GLFW by default.  You need to [enable EGL when
+[GLFW\_CONTEXT\_CREATION\_API](http://www.glfw.org/docs/latest/window_guide.html#window_hints_ctx)
-compiling](http://www.glfw.org/docs/latest/compile.html) GLFW to use this.
+hint for how to select EGL.
 
-The `glfwinfo` tool is included in the GLFW source tree as `tests/glfwinfo.c`
+Please verify that context creation also fails with the `glfwinfo` tool before
-and is built along with the library.  It lets you request any kind of context
+reporting it as a bug.  This tool is included in the GLFW source tree as
-and framebuffer format supported by the GLFW API without having to recompile.
+`tests/glfwinfo.c` and is built along with the library.  It has switches for all
-If context creation fails in your application, please verify that it also fails
+GLFW context and framebuffer hints.  Run `glfwinfo -h` for a complete list.
-with this tool before reporting it as a bug.
 
-In addition to the information above (OS and GLFW version), always include the
+Always include the __operating system name and version__ (i.e. `Windows
-__GPU model and driver version__ (i.e. `GeForce GTX660 with 352.79`) when
+7 64-bit` or `Ubuntu 15.10`).  If you are using an official release of GLFW,
-reporting this kind of bug.
+include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the
+__GLFW commit ID__ (i.e.  `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
+
+Please also include the __GLFW version string__ (`3.2.0 X11 EGL clock_gettime
+/dev/js XI Xf86vm`), as described
+[here](http://www.glfw.org/docs/latest/intro.html#intro_version_string), the
+__GPU model and driver version__ (i.e. `GeForce GTX660 with 352.79`), and the
+__output of `glfwinfo`__ (with switches matching any hints you set in your
+code) when reporting this kind of bug.  If this tool doesn't run on the machine,
+mention that instead.
+
+
+#### Quick template
+
+```
+OS and version:
+GPU and driver:
+Release or commit:
+Version string:
+`glfwinfo` output:
+```
 
 
 ### Reporting a monitor or video mode bug
@@ -63,23 +133,40 @@ __Note:__ On headless systems on some platforms, no monitors are reported.  This
 causes glfwGetPrimaryMonitor to return `NULL`, which not all applications are
 prepared for.
 
-__Note:__ Some third-party tools report more video modes than those approved of
+__Note:__ Some third-party tools report more video modes than are approved of
-by the OS.  For safety and compatbility, GLFW only reports video modes the OS
+by the OS.  For safety and compatibility, GLFW only reports video modes the OS
 wants programs to use.  This is not a bug.
 
 The `monitors` tool is included in the GLFW source tree as `tests/monitors.c`
-and is built along with the library.  lists all information about connected
+and is built along with the library.  It lists all information GLFW provides
-monitors made available by GLFW.
+about monitors it detects.
 
-In addition to the information above (OS and GLFW version), please also include
+Always include the __operating system name and version__ (i.e. `Windows
-the output of the `monitors` tool when reporting this kind of bug.  If it
+7 64-bit` or `Ubuntu 15.10`).  If you are using an official release of GLFW,
-doesn't work at all, please mention this.
+include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the
+__GLFW commit ID__ (i.e.  `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
+
+Please also include any __error messages__ provided to your application via the
+[error
+callback](http://www.glfw.org/docs/latest/intro_guide.html#error_handling) and
+the __output of `monitors`__ when reporting this kind of bug.  If this tool
+doesn't run on the machine, mention this instead.
 
 
-### Reporting a window event bug
+#### Quick template
 
-__Note:__ While GLFW tries to provide the exact same behavior between platforms,
+```
-the exact ordering of related window events will sometimes differ.
+OS and version:
+Release or commit:
+Error messages:
+`monitors` output:
+```
+
+
+### Reporting an input or event bug
+
+__Note:__ While GLFW tries to provide the same behavior across platforms, the
+exact ordering of related window events will sometimes differ.
 
 The `events` tool is included in the GLFW source tree as `tests/events.c` and is
 built along with the library.  It prints all information provided to every
@@ -87,20 +174,109 @@ callback supported by GLFW as events occur.  Each event is listed with the time
 and a unique number to make discussions about event logs easier.  The tool has
 command-line options for creating multiple windows and full screen windows.
 
+Always include the __operating system name and version__ (i.e. `Windows
+7 64-bit` or `Ubuntu 15.10`).  If you are using an official release of GLFW,
+include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the
+__GLFW commit ID__ (i.e.  `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
+
+Please also include any __error messages__ provided to your application via the
+[error
+callback](http://www.glfw.org/docs/latest/intro_guide.html#error_handling) and
+if relevant, the __output of `events`__ when reporting this kind of bug.  If
+this tool doesn't run on the machine, mention this instead.
+
+
+#### Quick template
+
+```
+OS and version:
+Release or commit:
+Error messages:
+`events` output:
+```
+
+
+### Reporting some other library bug
+
+Always include the __operating system name and version__ (i.e. `Windows
+7 64-bit` or `Ubuntu 15.10`).  If you are using an official release of GLFW,
+include the __GLFW release version__ (i.e. `3.1.2`), otherwise include the
+__GLFW commit ID__ (i.e.  `3795d78b14ef06008889cc422a1fb8d642597751`) from Git.
+
+Please also include any __error messages__ provided to your application via the
+[error
+callback](http://www.glfw.org/docs/latest/intro_guide.html#error_handling), if
+relevant.
+
+
+#### Quick template
+
+```
+OS and version:
+Release or commit:
+Error messages:
+```
+
 
 ### Reporting a documentation bug
 
-If you found the error in the generated documentation then it's fine to just
+If you found a bug in the documentation, including this file, then it's fine to
-link to that webpage.  You don't need to figure out which documentation source
+just link to that web page or mention that source file.  You don't need to match
-file the text comes from.
+the source to the output or vice versa.
+
+
+### Reporting a website bug
+
+If the bug is in the documentation (anything under `/docs/`) then please see the
+section above.  Bugs in the rest of the site are reported to to the [website
+source repository](https://github.com/glfw/website/issues).
+
+
+## Requesting a feature
+
+Please explain why you need the feature and how you intend to use it.  If you
+have a specific API design in mind, please add that as well.  If you have or are
+planning to write code for the feature, see the section below.
 
 
 ## Contributing a bug fix
 
-There should be text here, but there isn't.
+Adding a complete bug fix involves:
+
+- Change log entry in `README.md`
+- Credits entries in `README.md` for all authors of the fix
 
 
 ## Contributing a feature
 
-This is not (yet) the text you are looking for.
+__Note:__ You _must_ mention if you have taken any code from outside sources,
+even if the licenses seem compatible.
+
+Adding a complete feature involves:
+
+- Change log entry in `README.md`
+- News entry in `docs/news.dox`
+- Guide documentation in `docs/window.dox`, `docs/input.dox`,
+    `docs/monitor.dox`, `docs/context.dox` or `docs/vulkan.dox`
+- Reference documentation in `include/GLFW/glfw3.h`
+- Credits entries in `README.md` for all authors of the feature
+
+If it requires platform-specific code, add at minimum stubs for the new platform
+function to all supported platforms.
+
+If it's a new callback, add support for it to `tests/event.c`.
+
+If it's a new monitor property, add support for it to `tests/monitor.c`.
+
+If it's a new OpenGL, OpenGL ES or Vulkan option or extension, add support for
+it to `tests/glfwinfo.c` and describe its use in `docs/compat.dox`.
+
+If it requires calling non-default DLLs on Windows, load these at runtime in
+`src/win32_init.c`.
+
+Please keep in mind that any part of the public API that has been included in
+a release cannot be changed until the next _major_ version.  Features can be
+added and existing parts can sometimes be overloaded (in the general sense of
+doing more things, not in the C++ sense), but code written to the API of one
+minor release should both compile and run on subsequent minor releases.