From b5aae7e9019edf600c58b8bafbc9dcb554850942 Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Tue, 21 Jun 2016 20:40:09 +0200 Subject: [PATCH] Documentation work [ci skip] --- .github/CONTRIBUTING.md | 53 +++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5c61fc5f..db2441a7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -36,8 +36,12 @@ the issue is labeled. __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. + +__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 @@ -165,8 +169,12 @@ 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. +__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 @@ -244,10 +252,16 @@ planning to write code for the feature, see the section below. __Note:__ You _must_ mention if you have taken any code from outside sources, even if the licenses seem compatible. -Adding a complete bug fix involves: +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. -- Change log entry in `README.md` -- Credits entries in `README.md` for all authors of 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 @@ -255,27 +269,24 @@ Adding a complete bug fix involves: __Note:__ You _must_ mention if you have taken any code from outside sources, even if the licenses seem compatible. -Adding a complete feature involves: +In addition to the code, a complete feature includes: -- 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 +- 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's a new callback, add support for it to `tests/event.c`. +If it adds a new callback, add support for it in `tests/event.c`. -If it's a new monitor property, add support for it to `tests/monitor.c`. +If it adds a new monitor property, add support for it in `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`. +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