glfw/.github/CONTRIBUTING.md

# Contribution Guide

## Contents

- [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 at run-time, start by setting an [error
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.

If your bug is already reported, please add any new information you have, or if
it already has everything, give it a :+1:.


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

__Note:__ Check the [Compiling
GLFW](http://www.glfw.org/docs/latest/compile.html) guide and or [Building
applications](http://www.glfw.org/docs/latest/build.html) guide for before
opening an issue of this kind.  Most issues are caused by a missing package or
linker flag.

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.

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 __full call stack__ of the crash, or if the crash does not occur in debug
mode, mention that instead.


#### Quick template

```
OS and version:
Release or commit:
Error messages:
Call stack:
```


### Reporting a context creation bug

__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),
[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.  See the
[GLFW\_CONTEXT\_CREATION\_API](http://www.glfw.org/docs/latest/window_guide.html#window_hints_ctx)
hint for how to select EGL.

Please verify that context creation also fails with the `glfwinfo` tool before
reporting it as a bug.  This tool is included in the GLFW source tree as
`tests/glfwinfo.c` and is built along with the library.  It has switches for all
GLFW context and framebuffer hints.  Run `glfwinfo -h` for a complete list.

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

__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 are approved of
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.  It lists all information GLFW provides
about monitors it detects.

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
the __output of `monitors`__ 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:
monitors output:
```


### Reporting an input or event bug

__Note:__ The exact ordering of related window events will sometimes differ.

__Note:__ Window moving and resizing (by the user) will block the main thread on some
platforms.  This is not a bug.  Set a [refresh
callback](http://www.glfw.org/docs/latest/window.html#window_refresh) if you
want to keep the window contents updated during a move or size operation.

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
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 a bug in the documentation, including this file, then it's fine to
just link to that web page or mention that source file.  You don't need to match
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

__Note:__ You _must_ mention if you have taken any code from outside sources,
even if the licenses seem compatible.

There is no preferred patch size.  A one character fix is very welcome, as is
a thousand line one, if that is the appropriate size for the fix.

In addition to the code, a complete bug fix includes:

- Change log entry in `README.md`, describing the incorrect behavior
- Credits entries for all authors of the bug fix

If the patch fixes a bug introduced after the last release, it should not get
a change log entry.


## Contributing a feature

__Note:__ You _must_ mention if you have taken any code from outside sources,
even if the licenses seem compatible.

In addition to the code, a complete feature includes:

- Change log entry in `README.md`, listing all new symbols
- News page entry, briefly describing the feature
- Guide documentation, with minimal examples, in the relevant guide
- Reference documentation, with all applicable tags
- Cross-references and mentions in appropriate places
- Credits entries 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 adds a new callback, add support for it in `tests/event.c`.

If it adds a new monitor property, add support for it in `tests/monitor.c`.

If it adds a new OpenGL, OpenGL ES or Vulkan option or extension, add support
for it in `tests/glfwinfo.c` and describe its use in `docs/compat.dox`.

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.