Added guide for contributing to GLM and coding style guide #798
This commit is contained in:
Christophe Riccio
parent
abdb9fa3a2
commit
b1e8bcad29
251
manual.md
251
manual.md
@ -86,14 +86,18 @@
|
||||
+ [8.2. Matrix transform](#section8_2)
|
||||
+ [8.3. Vector types](#section8_3)
|
||||
+ [8.4. Lighting](#section8_4)
|
||||
+ [9. References](#section9)
|
||||
+ [9.1. OpenGL specifications](#section9_1)
|
||||
+ [9.2. External links](#section9_2)
|
||||
+ [9.3. Projects using GLM](#section9_3)
|
||||
+ [9.4. Tutorials using GLM](#section9_4)
|
||||
+ [9.5. Equivalent for other languages](#section9_5)
|
||||
+ [9.6. Alternatives to GLM](#section9_6)
|
||||
+ [9.7. Acknowledgements](#section9_7)
|
||||
+ [9. Contributing to GLM](#section9)
|
||||
+ [9.1. Submitting bug reports](#section9_1)
|
||||
+ [9.2. Contributing to GLM with pull request](#section9_2)
|
||||
+ [9.3. Coding style](#section9_3)
|
||||
+ [10. References](#section10)
|
||||
+ [10.1. OpenGL specifications](#section10_1)
|
||||
+ [10.2. External links](#section10_2)
|
||||
+ [10.3. Projects using GLM](#section10_3)
|
||||
+ [10.4. Tutorials using GLM](#section10_4)
|
||||
+ [10.5. Equivalent for other languages](#section10_5)
|
||||
+ [10.6. Alternatives to GLM](#section10_6)
|
||||
+ [10.7. Acknowledgements](#section10_7)
|
||||
|
||||
---
|
||||
## <a name="section0"></a> Licenses
|
||||
@ -1477,19 +1481,234 @@ glm::vec3 lighting(intersection const& Intersection, material const& Material, l
|
||||
```
|
||||
|
||||
---
|
||||
## <a name="section9"></a> 9. References
|
||||
## <a name="section9"></a> 9. Contributing to GLM
|
||||
|
||||
### <a name="section9_1"></a> 9.1. OpenGL specifications
|
||||
### <a name="section9_1"></a> 9.1. Submitting bug reports
|
||||
|
||||
Bug should be reported on Github using the [issue page](https://github.com/g-truc/glm/issues).
|
||||
|
||||
A minimal code to reproduce the issue will help.
|
||||
|
||||
Additional, bugs can be configuration specific. We can report the configuration by defining `GLM_FORCE_MESSAGES` before including GLM headers then build and copy paste the build messages GLM will output.
|
||||
|
||||
```cpp
|
||||
#define GLM_FORCE_MESSAGES
|
||||
#include <glm/glm.hpp>
|
||||
```
|
||||
|
||||
An example of build messages generated by GLM:
|
||||
```
|
||||
GLM: 0.9.9.1
|
||||
GLM: C++ 17 with extensions
|
||||
GLM: GCC compiler detected"
|
||||
GLM: x86 64 bits with AVX instruction set build target
|
||||
GLM: Linux platform detected
|
||||
GLM: GLM_FORCE_SWIZZLE is undefined. swizzling functions or operators are disabled.
|
||||
GLM: GLM_FORCE_SIZE_T_LENGTH is undefined. .length() returns a glm::length_t, a typedef of int following GLSL.
|
||||
GLM: GLM_FORCE_UNRESTRICTED_GENTYPE is undefined. Follows strictly GLSL on valid function genTypes.
|
||||
GLM: GLM_FORCE_DEPTH_ZERO_TO_ONE is undefined. Using negative one to one depth clip space.
|
||||
GLM: GLM_FORCE_LEFT_HANDED is undefined. Using right handed coordinate system.
|
||||
```
|
||||
|
||||
### <a name="section9_2"></a> 9.2. Contributing to GLM with pull request
|
||||
|
||||
This tutorial will show us how to successfully contribute a bug-fix to GLM using GitHub's Pull Request workflow.
|
||||
|
||||
We will be typing git commands in the Terminal. Mac and Linux users may have git pre-installed. You can download git from [here](http://git-scm.com/downloads).
|
||||
|
||||
The tutorial assumes you have some basic understanding of git concepts - repositories, branches, commits, etc. Explaining it all from scratch is beyond the scope of this tutorial. Some good links to learn git basics are: [Link 1](http://git-scm.com/book/en/Getting-Started-Git-Basics), [Link 2](https://www.atlassian.com/git/tutorial/git-basics)
|
||||
|
||||
#### Step 1: Setup our GLM Fork
|
||||
|
||||
We will make our changes in our own copy of the GLM sitory. On the GLM GitHub repo and we press the Fork button.
|
||||
We need to download a copy of our fork to our local machine. In the terminal, type:
|
||||
|
||||
```
|
||||
>>> git clone <our-repository-fork-git-url>
|
||||
```
|
||||
|
||||
This will clone our fork repository into the current folder.
|
||||
|
||||
We can find our repository git url on the Github reposotory page. The url looks like this: `https://github.com/<our-username>/<repository-name>.git`
|
||||
|
||||
#### Step 2: Synchronizing our fork
|
||||
|
||||
We can use the following command to add `upstream` (original project repository) as a remote repository so that we can fetch the latest GLM commits into our branch and keep our forked copy is synchronized.
|
||||
|
||||
```
|
||||
>>> git remote add upstream https://github.com/processing/processing.git
|
||||
```
|
||||
|
||||
To synchronize our fork to the latest commit in the GLM repository, we can use the following command:
|
||||
|
||||
```
|
||||
>>> git fetch upstream
|
||||
```
|
||||
|
||||
Then, we can merge the remote master branch to our current branch:
|
||||
|
||||
```
|
||||
>>> git merge upstream/master
|
||||
```
|
||||
|
||||
Now our local copy of our fork has been synchronized. However, the fork's copy is not updated on GitHub's servers yet. To do that, use:
|
||||
|
||||
```
|
||||
>>> git push origin master
|
||||
```
|
||||
|
||||
#### Step 3: Modifying our GLM Fork
|
||||
|
||||
Our fork is now setup and we are ready to modify GLM to fix a bug.
|
||||
|
||||
It's a good practice to make changes in our fork in a separate branch than the master branch because we can submit only one pull request per branch.
|
||||
|
||||
Before creating a new branch, it's best to synchronize our fork and then create a new branch from the latest master branch.
|
||||
|
||||
If we are not on the master branch, we should switch to it using:
|
||||
```
|
||||
>>> git checkout master
|
||||
```
|
||||
|
||||
To create a new branch called `bugifx`, we use:
|
||||
```
|
||||
git branch bugfix
|
||||
```
|
||||
|
||||
Once the code changes for the fix is done, we need to commit the changes:
|
||||
```
|
||||
>>> git commit -m "Resolve the issue that caused problem with a specific fix #432"
|
||||
```
|
||||
|
||||
The commit message should be as specific as possible and finished by the bug number in the [GLM GitHub issue page](https://github.com/g-truc/glm/issues)
|
||||
|
||||
Finally, we need to push our changes in our branch to our GitHub fork using:
|
||||
```
|
||||
>>> git push origin bugfix
|
||||
```
|
||||
|
||||
Some things to keep in mind for a pull request:
|
||||
* Keep it minimal: Try to make the minimum required changes to fix the issue. If we have added any debugging code, we should remove it.
|
||||
* A fix at a time: The pull request should deal with one issue at a time only, unless two issue are so interlinked they must be fixed together.
|
||||
* Write a test: GLM is largely unit tests. Unit tests are in `glm/test` directory. We should also add tests for the fixes we provide to ensure future regression doesn't happen.
|
||||
* No whitespace changes: Avoid unnecessary formatting or whitespace changes in other parts of the code. Be careful with auto-format options in the code editor which can cause wide scale formatting changes.
|
||||
* Follow [GLM Code Style](#section9_3) for consistency.
|
||||
* Tests passes: Make sure GLM build and tests don't fail because of the changes.
|
||||
|
||||
#### Step 4: Submitting a Pull Request
|
||||
|
||||
We need to submit a pull request from the `bugfix` branch to GLM's master branch.
|
||||
|
||||
On the fork github page, we can click on the *Pull Request* button. Then we can describe our pull request. Finally we press *Send Pull Request*.
|
||||
|
||||
Please be patient and give them some time to go through it.
|
||||
|
||||
The pull request review may suggest additional changes. So we can make those changes in our branch, and push those changes to our fork repository. Our pull request will always include the latest changes in our branch on GitHub, so we don't need to resubmit the pull request.
|
||||
|
||||
Once your changes have been accepted, a project maintainer will merge our pull request.
|
||||
|
||||
We are grateful to the users for their time and effort in contributing fixes.
|
||||
|
||||
### <a name="section9_3"></a> 9.3. Coding style
|
||||
|
||||
#### Indentation
|
||||
|
||||
Always tabs. Never spaces.
|
||||
|
||||
#### Spacing
|
||||
|
||||
No space after if. Use if(blah) not if (blah). Example if/else block:
|
||||
|
||||
```cpp
|
||||
if(blah)
|
||||
{
|
||||
// yes like this
|
||||
}
|
||||
else
|
||||
{
|
||||
// something besides
|
||||
}
|
||||
```
|
||||
|
||||
Single line if blocks:
|
||||
```cpp
|
||||
if(blah)
|
||||
// yes like this
|
||||
else
|
||||
// something besides
|
||||
```
|
||||
|
||||
No spaces inside parens:
|
||||
```cpp
|
||||
if (blah) // No
|
||||
if( blah ) // No
|
||||
if ( blah ) // No
|
||||
if(blah) // Yes
|
||||
```
|
||||
|
||||
Use spaces before/after commas:
|
||||
```cpp
|
||||
someFunction(apple,bear,cat); // No
|
||||
someFunction(apple, bear, cat); // Yes
|
||||
```
|
||||
|
||||
Use spaces before/after use of `+, -, *, /, %, >>, <<, |, &, ^, ||, &&` operators:
|
||||
```cpp
|
||||
vec4 v = a + b;
|
||||
```
|
||||
|
||||
#### Blank lines
|
||||
|
||||
One blank line after the function blocks.
|
||||
|
||||
#### Comments
|
||||
|
||||
Always one space after the // in single line comments
|
||||
|
||||
One space before // at the end of a line (that has code as well)
|
||||
|
||||
Try to use // comments inside functions, to make it easier to remove a whole block via /* */
|
||||
|
||||
#### Cases
|
||||
|
||||
```cpp
|
||||
#define GLM_MY_DEFINE 76
|
||||
|
||||
class myClass
|
||||
{};
|
||||
|
||||
myClass const MyClass;
|
||||
|
||||
namespace glm{ // glm namespace is for public code
|
||||
namespace detail // glm::detail namespace is for implementation detail
|
||||
{
|
||||
float myFunction(vec2 const& V)
|
||||
{
|
||||
return V.x + V.y;
|
||||
}
|
||||
|
||||
float myFunction(vec2 const* const V)
|
||||
{
|
||||
return V->x + V->y;
|
||||
}
|
||||
}//namespace detail
|
||||
}//namespace glm
|
||||
```
|
||||
|
||||
---
|
||||
## <a name="section10"></a> 10. References
|
||||
|
||||
### <a name="section10_1"></a> 10.1. OpenGL specifications
|
||||
|
||||
* OpenGL 4.3 core specification
|
||||
* [GLSL 4.30 specification](http://www.opengl.org/registry/doc/GLSLangSpec.4.30.7.diff.pdf)
|
||||
{width="2.859722222222222in" height="1.6083333333333334in"}- [*GLU 1.3 specification*](http://www.opengl.org/documentation/specs/glu/glu1_3.pdf)
|
||||
|
||||
### <a name="section9_2"></a> 9.2. External links
|
||||
### <a name="section10_2"></a> 10.2. External links
|
||||
|
||||
* [GLM on stackoverflow](http://stackoverflow.com/search?q=GLM)
|
||||
|
||||
### <a name="section9_3"></a> 9.3. Projects using GLM
|
||||
### <a name="section10_3"></a> 10.3. Projects using GLM
|
||||
|
||||
***[Leo’s Fortune](http://www.leosfortune.com/)***
|
||||
|
||||
@ -1561,7 +1780,7 @@ LibreOffice includes several applications that make it the most powerful Free an
|
||||
|
||||
[***Are you using GLM in a project?***](mailto:glm@g-truc.net)
|
||||
|
||||
### <a name="section9_4"></a> 9.4. Tutorials using GLM
|
||||
### <a name="section10_4"></a> 10.4. Tutorials using GLM
|
||||
|
||||
* [Sascha Willems' Vulkan examples](https://github.com/SaschaWillems/Vulkan), Examples and demos for the new Vulkan API
|
||||
* [VKTS](https://github.com/McNopper/Vulkan) Vulkan examples using VulKan ToolS (VKTS)
|
||||
@ -1579,7 +1798,7 @@ LibreOffice includes several applications that make it the most powerful Free an
|
||||
* [Learn OpenGL](http://learnopengl.com/), OpenGL tutorial
|
||||
* [***Are you using GLM in a tutorial?***](mailto:glm@g-truc.net)
|
||||
|
||||
### <a name="section9_5"></a> 9.5. Equivalent for other languages
|
||||
### <a name="section10_5"></a> 10.5. Equivalent for other languages
|
||||
|
||||
* [*cglm*](https://github.com/recp/cglm): OpenGL Mathematics (glm) for C.
|
||||
* [*GlmSharp*](https://github.com/Philip-Trettner/GlmSharp): Open-source semi-generated GLM-flavored math library for .NET/C\#.
|
||||
@ -1592,14 +1811,14 @@ LibreOffice includes several applications that make it the most powerful Free an
|
||||
* [glm-rs](https://github.com/dche/glm-rs): GLSL mathematics for Rust programming language
|
||||
* [glmpython](https://github.com/Queatz/glmpython): GLM math library for Python
|
||||
|
||||
### <a name="section9_6"></a> 9.6. Alternatives to GLM
|
||||
### <a name="section10_6"></a> 10.6. Alternatives to GLM
|
||||
|
||||
* [*CML*](http://cmldev.net/): The CML (Configurable Math Library) is a free C++ math library for games and graphics.
|
||||
* [*Eigen*](http://eigen.tuxfamily.org/): A more heavy weight math library for general linear algebra in C++.
|
||||
* [*glhlib*](http://glhlib.sourceforge.net/): A much more than glu C library.
|
||||
* Are you using or developing an alternative library to GLM?
|
||||
|
||||
### <a name="section9_7"></a> 9.7. Acknowledgements
|
||||
### <a name="section10_7"></a> 10.7. Acknowledgements
|
||||
|
||||
GLM is developed and maintained by [*Christophe Riccio*](http://www.g-truc.net) but many contributors have made this project what it is.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user