diff options
Diffstat (limited to '3rdparty/glfw/source/docs/CONTRIBUTING.md')
| -rw-r--r-- | 3rdparty/glfw/source/docs/CONTRIBUTING.md | 391 |
1 files changed, 0 insertions, 391 deletions
diff --git a/3rdparty/glfw/source/docs/CONTRIBUTING.md b/3rdparty/glfw/source/docs/CONTRIBUTING.md deleted file mode 100644 index 11ddf09..0000000 --- a/3rdparty/glfw/source/docs/CONTRIBUTING.md +++ /dev/null @@ -1,391 +0,0 @@ -# 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 line one, 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. - |