1# Contribution Guide 2 3## Contents 4 5- [Asking a question](#asking-a-question) 6- [Reporting a bug](#reporting-a-bug) 7 - [Reporting a compile or link bug](#reporting-a-compile-or-link-bug) 8 - [Reporting a segfault or other crash bug](#reporting-a-segfault-or-other-crash-bug) 9 - [Reporting a context creation bug](#reporting-a-context-creation-bug) 10 - [Reporting a monitor or video mode bug](#reporting-a-monitor-or-video-mode-bug) 11 - [Reporting a window, input or event bug](#reporting-a-window-input-or-event-bug) 12 - [Reporting some other library bug](#reporting-some-other-library-bug) 13 - [Reporting a documentation bug](#reporting-a-documentation-bug) 14 - [Reporting a website bug](#reporting-a-website-bug) 15- [Requesting a feature](#requesting-a-feature) 16- [Contributing a bug fix](#contributing-a-bug-fix) 17- [Contributing a feature](#contributing-a-feature) 18 19 20## Asking a question 21 22Questions about how to use GLFW should be asked either in the [support 23section](https://discourse.glfw.org/c/support) of the forum, under the [Stack 24Overflow tag](https://stackoverflow.com/questions/tagged/glfw) or [Game 25Development tag](https://gamedev.stackexchange.com/questions/tagged/glfw) on 26Stack Exchange or in the IRC channel `#glfw` on 27[Freenode](http://freenode.net/). 28 29Questions about the design or implementation of GLFW or about future plans 30should be asked in the [dev section](https://discourse.glfw.org/c/dev) of the 31forum or in the IRC channel. Please don't open a GitHub issue to discuss design 32questions without first checking with a maintainer. 33 34 35## Reporting a bug 36 37If GLFW is behaving unexpectedly at run-time, start by setting an [error 38callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling). 39GLFW will often tell you the cause of an error via this callback. If it 40doesn't, that might be a separate bug. 41 42If GLFW is crashing or triggering asserts, make sure that all your object 43handles and other pointers are valid. 44 45For bugs where it makes sense, a short, self contained example is absolutely 46invaluable. Just put it inline in the body text. Note that if the bug is 47reproducible with one of the test programs that come with GLFW, just mention 48that instead. 49 50__Don't worry about adding too much information__. Unimportant information can 51be abbreviated or removed later, but missing information can stall bug fixing, 52especially when your schedule doesn't align with that of the maintainer. 53 54__Please provide text as text, not as images__. This includes code, error 55messages and any other text. Text in images cannot be found by other users 56searching for the same problem and may have to be re-typed by maintainers when 57debugging. 58 59You don't need to manually indent your code or other text to quote it with 60GitHub Markdown; just surround it with triple backticks: 61 62 ``` 63 Some quoted text. 64 ``` 65 66You can also add syntax highlighting by appending the common file extension: 67 68 ```c 69 int five(void) 70 { 71 return 5; 72 } 73 ``` 74 75There are issue labels for both platforms and GPU manufacturers, so there is no 76need to mention these in the subject line. If you do, it will be removed when 77the issue is labeled. 78 79If your bug is already reported, please add any new information you have, or if 80it already has everything, give it a :+1:. 81 82 83### Reporting a compile or link bug 84 85__Note:__ GLFW needs many system APIs to do its job, which on some platforms 86means linking to many system libraries. If you are using GLFW as a static 87library, that means your application needs to link to these in addition to GLFW. 88 89__Note:__ Check the [Compiling 90GLFW](https://www.glfw.org/docs/latest/compile.html) guide and or [Building 91applications](https://www.glfw.org/docs/latest/build.html) guide for before 92opening an issue of this kind. Most issues are caused by a missing package or 93linker flag. 94 95Always include the __operating system name and version__ (e.g. `Windows 967 64-bit` or `Ubuntu 15.10`) and the __compiler name and version__ (e.g. `Visual 97C++ 2015 Update 2`). If you are using an official release of GLFW, 98include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the 99__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. 100 101Please also include the __complete build log__ from your compiler and linker, 102even if it's long. It can always be shortened later, if necessary. 103 104 105#### Quick template 106 107``` 108OS and version: 109Compiler version: 110Release or commit: 111Build log: 112``` 113 114 115### Reporting a segfault or other crash bug 116 117Always include the __operating system name and version__ (e.g. `Windows 1187 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, 119include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the 120__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. 121 122Please also include any __error messages__ provided to your application via the 123[error 124callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling) and 125the __full call stack__ of the crash, or if the crash does not occur in debug 126mode, mention that instead. 127 128 129#### Quick template 130 131``` 132OS and version: 133Release or commit: 134Error messages: 135Call stack: 136``` 137 138 139### Reporting a context creation bug 140 141__Note:__ Windows ships with graphics drivers that do not support OpenGL. If 142GLFW says that your machine lacks support for OpenGL, it very likely does. 143Install drivers from the computer manufacturer or graphics card manufacturer 144([Nvidia](https://www.geforce.com/drivers), 145[AMD](https://www.amd.com/en/support), 146[Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to 147fix this. 148 149__Note:__ AMD only supports OpenGL ES on Windows via EGL. See the 150[GLFW\_CONTEXT\_CREATION\_API](https://www.glfw.org/docs/latest/window_guide.html#window_hints_ctx) 151hint for how to select EGL. 152 153Please verify that context creation also fails with the `glfwinfo` tool before 154reporting it as a bug. This tool is included in the GLFW source tree as 155`tests/glfwinfo.c` and is built along with the library. It has switches for all 156GLFW context and framebuffer hints. Run `glfwinfo -h` for a complete list. 157 158Always include the __operating system name and version__ (e.g. `Windows 1597 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, 160include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the 161__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. 162 163If you are running your program in a virtual machine, please mention this and 164include the __VM name and version__ (e.g. `VirtualBox 5.1`). 165 166Please also include the __GLFW version string__ (`3.2.0 X11 EGL clock_gettime 167/dev/js`), as described 168[here](https://www.glfw.org/docs/latest/intro.html#intro_version_string), the 169__GPU model and driver version__ (e.g. `GeForce GTX660 with 352.79`), and the 170__output of `glfwinfo`__ (with switches matching any hints you set in your 171code) when reporting this kind of bug. If this tool doesn't run on the machine, 172mention that instead. 173 174 175#### Quick template 176 177``` 178OS and version: 179GPU and driver: 180Release or commit: 181Version string: 182glfwinfo output: 183``` 184 185 186### Reporting a monitor or video mode bug 187 188__Note:__ On headless systems on some platforms, no monitors are reported. This 189causes glfwGetPrimaryMonitor to return `NULL`, which not all applications are 190prepared for. 191 192__Note:__ Some third-party tools report more video modes than are approved of 193by the OS. For safety and compatibility, GLFW only reports video modes the OS 194wants programs to use. This is not a bug. 195 196The `monitors` tool is included in the GLFW source tree as `tests/monitors.c` 197and is built along with the library. It lists all information GLFW provides 198about monitors it detects. 199 200Always include the __operating system name and version__ (e.g. `Windows 2017 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, 202include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the 203__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. 204 205If you are running your program in a virtual machine, please mention this and 206include the __VM name and version__ (e.g. `VirtualBox 5.1`). 207 208Please also include any __error messages__ provided to your application via the 209[error 210callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling) and 211the __output of `monitors`__ when reporting this kind of bug. If this tool 212doesn't run on the machine, mention this instead. 213 214 215#### Quick template 216 217``` 218OS and version: 219Release or commit: 220Error messages: 221monitors output: 222``` 223 224 225### Reporting a window, input or event bug 226 227__Note:__ The exact ordering of related window events will sometimes differ. 228 229__Note:__ Window moving and resizing (by the user) will block the main thread on 230some platforms. This is not a bug. Set a [refresh 231callback](https://www.glfw.org/docs/latest/window.html#window_refresh) if you 232want to keep the window contents updated during a move or size operation. 233 234The `events` tool is included in the GLFW source tree as `tests/events.c` and is 235built along with the library. It prints all information provided to every 236callback supported by GLFW as events occur. Each event is listed with the time 237and a unique number to make discussions about event logs easier. The tool has 238command-line options for creating multiple windows and full screen windows. 239 240Always include the __operating system name and version__ (e.g. `Windows 2417 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, 242include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the 243__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. 244 245If you are running your program in a virtual machine, please mention this and 246include the __VM name and version__ (e.g. `VirtualBox 5.1`). 247 248Please also include any __error messages__ provided to your application via the 249[error 250callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling) and 251if relevant, the __output of `events`__ when reporting this kind of bug. If 252this tool doesn't run on the machine, mention this instead. 253 254__X11:__ If possible, please include what desktop environment (e.g. GNOME, 255Unity, KDE) and/or window manager (e.g. Openbox, dwm, Window Maker) you are 256running. If the bug is related to keyboard input, please include any input 257method (e.g. ibus, SCIM) you are using. 258 259 260#### Quick template 261 262``` 263OS and version: 264Release or commit: 265Error messages: 266events output: 267``` 268 269 270### Reporting some other library bug 271 272Always include the __operating system name and version__ (e.g. `Windows 2737 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, 274include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the 275__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. 276 277Please also include any __error messages__ provided to your application via the 278[error 279callback](https://www.glfw.org/docs/latest/intro_guide.html#error_handling), if 280relevant. 281 282 283#### Quick template 284 285``` 286OS and version: 287Release or commit: 288Error messages: 289``` 290 291 292### Reporting a documentation bug 293 294If you found a bug in the documentation, including this file, then it's fine to 295just link to that web page or mention that source file. You don't need to match 296the source to the output or vice versa. 297 298 299### Reporting a website bug 300 301If the bug is in the documentation (anything under `/docs/`) then please see the 302section above. Bugs in the rest of the site are reported to the [website 303source repository](https://github.com/glfw/website/issues). 304 305 306## Requesting a feature 307 308Please explain why you need the feature and how you intend to use it. If you 309have a specific API design in mind, please add that as well. If you have or are 310planning to write code for the feature, see the section below. 311 312If there already is a request for the feature you need, add your specific use 313case unless it is already mentioned. If it is, give it a :+1:. 314 315 316## Contributing a bug fix 317 318__Note:__ You must have all necessary [intellectual 319property rights](https://en.wikipedia.org/wiki/Intellectual_property) to any 320code you contribute. If you did not write the code yourself, you must explain 321where it came from and under what license you received it. Even code using the 322same license as GLFW may not be copied without attribution. 323 324__There is no preferred patch size__. A one character fix is just as welcome as 325a thousand line one, if that is the appropriate size for the fix. 326 327In addition to the code, a complete bug fix includes: 328 329- Change log entry in `README.md`, describing the incorrect behavior 330- Credits entries for all authors of the bug fix 331 332Bug fixes will not be rejected because they don't include all the above parts, 333but please keep in mind that maintainer time is finite and that there are many 334other bugs and features to work on. 335 336If the patch fixes a bug introduced after the last release, it should not get 337a change log entry. 338 339If you haven't already, read the excellent article [How to Write a Git Commit 340Message](https://chris.beams.io/posts/git-commit/). 341 342 343## Contributing a feature 344 345__Note:__ You must have all necessary rights to any code you contribute. If you 346did not write the code yourself, you must explain where it came from and under 347what license. Even code using the same license as GLFW may not be copied 348without attribution. 349 350__Note:__ If you haven't already implemented the feature, check first if there 351already is an open issue for it and if it's already being developed in an 352[experimental branch](https://github.com/glfw/glfw/branches/all). 353 354__There is no preferred patch size__. A one character change is just as welcome 355as one adding a thousand line one, if that is the appropriate size for the 356feature. 357 358In addition to the code, a complete feature includes: 359 360- Change log entry in `README.md`, listing all new symbols 361- News page entry, briefly describing the feature 362- Guide documentation, with minimal examples, in the relevant guide 363- Reference documentation, with all applicable tags 364- Cross-references and mentions in appropriate places 365- Credits entries for all authors of the feature 366 367If the feature requires platform-specific code, at minimum stubs must be added 368for the new platform function to all supported and experimental platforms. 369 370If it adds a new callback, support for it must be added to `tests/event.c`. 371 372If it adds a new monitor property, support for it must be added to 373`tests/monitor.c`. 374 375If it adds a new OpenGL, OpenGL ES or Vulkan option or extension, support 376for it must be added to `tests/glfwinfo.c` and the behavior of the library when 377the extension is missing documented in `docs/compat.dox`. 378 379If you haven't already, read the excellent article [How to Write a Git Commit 380Message](https://chris.beams.io/posts/git-commit/). 381 382Features will not be rejected because they don't include all the above parts, 383but please keep in mind that maintainer time is finite and that there are many 384other features and bugs to work on. 385 386Please also keep in mind that any part of the public API that has been included 387in a release cannot be changed until the next _major_ version. Features can be 388added and existing parts can sometimes be overloaded (in the general sense of 389doing more things, not in the C++ sense), but code written to the API of one 390minor release should both compile and run on subsequent minor releases. 391 392