diff options
Diffstat (limited to 'libs/glfw-3.3.8/docs/CONTRIBUTING.md')
| -rw-r--r-- | libs/glfw-3.3.8/docs/CONTRIBUTING.md | 391 |
1 files changed, 391 insertions, 0 deletions
diff --git a/libs/glfw-3.3.8/docs/CONTRIBUTING.md b/libs/glfw-3.3.8/docs/CONTRIBUTING.md new file mode 100644 index 0000000..050c1be --- /dev/null +++ b/libs/glfw-3.3.8/docs/CONTRIBUTING.md @@ -0,0 +1,391 @@ +# Contribution Guide + +## Contents + +- [Asking a question](#asking-a-question) +- [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 a window, input or event bug](#reporting-a-window-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) + + +## Asking a question + +Questions about how to use GLFW should be asked either in the [support +section](https://discourse.glfw.org/c/support) of the forum, under the [Stack +Overflow tag](https://stackoverflow.com/questions/tagged/glfw) or [Game +Development tag](https://gamedev.stackexchange.com/questions/tagged/glfw) on +Stack Exchange or in the IRC channel `#glfw` on +[Libera.Chat](https://libera.chat/). + +Questions about the design or implementation of GLFW or about future plans +should be asked in the [dev section](https://discourse.glfw.org/c/dev) of the +forum or in the IRC channel. Please don't open a GitHub issue to discuss design +questions without first checking with a maintainer. + + +## Reporting a bug + +If GLFW is behaving unexpectedly at run-time, start by setting an [error +callback](https://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. + +For bugs where it makes sense, a short, self contained example is absolutely +invaluable. Just put it inline in the body text. Note that if the bug is +reproducible with one of the test programs that come with GLFW, just mention +that instead. + +__Don't worry about adding too much information__. Unimportant information can +be abbreviated or removed later, but missing information can stall bug fixing, +especially when your schedule doesn't align with that of the maintainer. + +__Please provide text as text, not as images__. This includes code, error +messages and any other text. Text in images cannot be found by other users +searching for the same problem and may have to be re-typed by maintainers when +debugging. + +You don't need to manually indent your code or other text to quote it with +GitHub Markdown; just surround it with triple backticks: + + ``` + Some quoted text. + ``` + +You can also add syntax highlighting by appending the common file extension: + + ```c + int five(void) + { + return 5; + } + ``` + +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](https://www.glfw.org/docs/latest/compile.html) guide and or [Building +applications](https://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__ (e.g. `Windows +7 64-bit` or `Ubuntu 15.10`) and the __compiler name and version__ (e.g. `Visual +C++ 2015 Update 2`). If you are using an official release of GLFW, +include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the +__GLFW commit ID__ (e.g. `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__ (e.g. `Windows +7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, +include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the +__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. + +Please also include any __error messages__ provided to your application via the +[error +callback](https://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](https://www.geforce.com/drivers), +[AMD](https://www.amd.com/en/support), +[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](https://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__ (e.g. `Windows +7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, +include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the +__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. + +If you are running your program in a virtual machine, please mention this and +include the __VM name and version__ (e.g. `VirtualBox 5.1`). + +Please also include the __GLFW version string__ (`3.2.0 X11 EGL clock_gettime +/dev/js`), as described +[here](https://www.glfw.org/docs/latest/intro.html#intro_version_string), the +__GPU model and driver version__ (e.g. `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__ (e.g. `Windows +7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, +include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the +__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. + +If you are running your program in a virtual machine, please mention this and +include the __VM name and version__ (e.g. `VirtualBox 5.1`). + +Please also include any __error messages__ provided to your application via the +[error +callback](https://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 a window, 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](https://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__ (e.g. `Windows +7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, +include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the +__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. + +If you are running your program in a virtual machine, please mention this and +include the __VM name and version__ (e.g. `VirtualBox 5.1`). + +Please also include any __error messages__ provided to your application via the +[error +callback](https://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. + +__X11:__ If possible, please include what desktop environment (e.g. GNOME, +Unity, KDE) and/or window manager (e.g. Openbox, dwm, Window Maker) you are +running. If the bug is related to keyboard input, please include any input +method (e.g. ibus, SCIM) you are using. + + +#### 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__ (e.g. `Windows +7 64-bit` or `Ubuntu 15.10`). If you are using an official release of GLFW, +include the __GLFW release version__ (e.g. `3.1.2`), otherwise include the +__GLFW commit ID__ (e.g. `3795d78b14ef06008889cc422a1fb8d642597751`) from Git. + +Please also include any __error messages__ provided to your application via the +[error +callback](https://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 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. + +If there already is a request for the feature you need, add your specific use +case unless it is already mentioned. If it is, give it a :+1:. + + +## Contributing a bug fix + +__Note:__ You must have all necessary [intellectual +property rights](https://en.wikipedia.org/wiki/Intellectual_property) to any +code you contribute. If you did not write the code yourself, you must explain +where it came from and under what license you received it. Even code using the +same license as GLFW may not be copied without attribution. + +__There is no preferred patch size__. A one character fix is just as welcome as +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 + +Bug fixes will not be rejected because they don't include all the above parts, +but please keep in mind that maintainer time is finite and that there are many +other bugs and features to work on. + +If the patch fixes a bug introduced after the last release, it should not get +a change log entry. + +If you haven't already, read the excellent article [How to Write a Git Commit +Message](https://chris.beams.io/posts/git-commit/). + + +## Contributing a feature + +__Note:__ You must have all necessary rights to any code you contribute. If you +did not write the code yourself, you must explain where it came from and under +what license. Even code using the same license as GLFW may not be copied +without attribution. + +__Note:__ If you haven't already implemented the feature, check first if there +already is an open issue for it and if it's already being developed in an +[experimental branch](https://github.com/glfw/glfw/branches/all). + +__There is no preferred patch size__. A one-character change is just as welcome +as one adding a thousand lines, if that is the appropriate size for the +feature. + +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 the feature requires platform-specific code, at minimum stubs must be added +for the new platform function to all supported and experimental platforms. + +If it adds a new callback, support for it must be added to `tests/event.c`. + +If it adds a new monitor property, support for it must be added to +`tests/monitor.c`. + +If it adds a new OpenGL, OpenGL ES or Vulkan option or extension, support +for it must be added to `tests/glfwinfo.c` and the behavior of the library when +the extension is missing documented in `docs/compat.dox`. + +If you haven't already, read the excellent article [How to Write a Git Commit +Message](https://chris.beams.io/posts/git-commit/). + +Features will not be rejected because they don't include all the above parts, +but please keep in mind that maintainer time is finite and that there are many +other features and bugs to work on. + +Please also 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. + |