mirror of
https://github.com/glfw/glfw.git
synced 2024-09-19 21:32:16 +00:00
Documentation work
This commit is contained in:
Camilla Berglund
parent
f2ba78e04b
commit
38856886e6
262
.github/CONTRIBUTING.md
vendored
262
.github/CONTRIBUTING.md
vendored
@ -1,35 +1,86 @@
|
||||
# Contribution Guide
|
||||
|
||||
This file is a work in progress and you can report errors or submit patches for
|
||||
it the same as any other file.
|
||||
## 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, make sure you have set an error callback.
|
||||
GLFW will often tell you the cause of an issue via this callback.
|
||||
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.
|
||||
|
||||
|
||||
### 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
|
||||
[here](http://www.glfw.org/docs/latest/intro.html#intro_version_string).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
### 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
|
||||
information.
|
||||
|
||||
In addition to the information above, always include the complete build log from
|
||||
your compiler and linker. Issue posts are editable so it can always be
|
||||
shortened later.
|
||||
```
|
||||
OS and version:
|
||||
Release or commit:
|
||||
Error messages:
|
||||
Call stack:
|
||||
```
|
||||
|
||||
|
||||
### 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),
|
||||
[Intel](https://www-ssl.intel.com/content/www/us/en/support/detect.html)) to
|
||||
[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. EGL support is not
|
||||
enabled in GLFW by default. You need to [enable EGL when
|
||||
compiling](http://www.glfw.org/docs/latest/compile.html) GLFW to use 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.
|
||||
|
||||
The `glfwinfo` tool is included in the GLFW source tree as `tests/glfwinfo.c`
|
||||
and is built along with the library. It lets you request any kind of context
|
||||
and framebuffer format supported by the GLFW API without having to recompile.
|
||||
If context creation fails in your application, please verify that it also fails
|
||||
with this tool before reporting it as a bug.
|
||||
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.
|
||||
|
||||
In addition to the information above (OS and GLFW version), always include the
|
||||
__GPU model and driver version__ (i.e. `GeForce GTX660 with 352.79`) when
|
||||
reporting this kind of 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 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
|
||||
by the OS. For safety and compatbility, GLFW only reports video modes the OS
|
||||
__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. lists all information about connected
|
||||
monitors made available by GLFW.
|
||||
and is built along with the library. It lists all information GLFW provides
|
||||
about monitors it detects.
|
||||
|
||||
In addition to the information above (OS and GLFW version), please also include
|
||||
the output of the `monitors` tool when reporting this kind of bug. If it
|
||||
doesn't work at all, please mention this.
|
||||
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.
|
||||
|
||||
|
||||
### 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
|
||||
link to that webpage. You don't need to figure out which documentation source
|
||||
file the text comes from.
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user