Conventions

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+## Contributing to raylib-python-cffi
+
+Hello contributors! Welcome to **raylib-python-cffi** AKA **pyray**! 
+
+Do you enjoy pyray and want to contribute? Nice! You can help with the following points:
+
+- `Python programming` - Can you write/review/test/improve the code? 
+- `Documentation/Tutorials/Example` - Can you write some tutorial/example?
+- `Porting Examples from C to Python` - Can you port the raylib examples in c to python?
+- `Build For Web` - Can you help [the issue](https://github.com/electronstudio/raylib-python-cffi/issues/58)?
+- `Testing` - Can you find some bugs in pyray?
+
+This document contains a set of guidelines to contribute to the project. These are mostly guidelines, not rules. 
+Use your best judgement, and feel free to propose changes to this document in a pull request.
+
+### raylib philosophy
+
+ - raylib is a tool to **ENJOY** videogames programming, every function in raylib is designed as a mini-tutorial on itself.
+ - raylib is **SIMPLE** and **EASY-TO-USE**, I tried to keep it compact with a small set of functions, if a function is too complex, better not including it.
+ - raylib is open source and free; educators and institutions can use this tool to **TEACH** videogames programming completely for free.
+ - raylib is collaborative; contribution of tutorials / code examples / bug fixes / code comments are highly appreciated.
+ - raylib's license (and its external libs respective licenses) allow using raylib on commercial projects.
+
+### raylib python coding conventions
+
+Despite being written in C, pyray is a python bindings for raylib. so the conventions are also python independent
+look at [Python API Coding Style Conventions](https://github.com/raysan5/raylib/wiki/raylib-coding-conventions), 
+
+Source code is extensively commented for that purpose, raylib primary learning method is:
+
+ > `Learn by reading code and examples`
+
+### Opening new Issues
+
+To open new issue for raylib (bug, enhancement, discussion...), just try to follow these rules:
+
+ - Make sure the issue has not already been reported before by searching on GitHub under Issues.
+ - If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a 
+ title and clear description, as much relevant information as possible, and a code sample demonstrating the unexpected behavior.
+ - If applies, attach some screenshot of the issue and a .zip file with the code sample and required resources.
+ - On issue description, add a brackets tag about the raylib module that relates to this issue. 
+ If don't know which module, just report the issue, I will review it.
+ - You can check other issues to see how is being done!
+
+### Sending a Pull-Request
+
+ - Make sure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+ - Don't send big pull requests (lots of changelists), they are difficult to review. It's better to send small pull requests, one at a time.
+ - Verify that changes don't break the build (at least on Windows platform). As many platforms where you can test it, the better, but don't worry
+ if you cannot test all the platforms.
+
+Thank you very much for your time! :)

PYTHON_API_CONVENTIONS.md

@@ -0,0 +1,193 @@
+## Python API Coding Style Conventions
+
+Here is a list with some code conventions used by raylib in python:
+
+| Code element        |             Convention              | Example                                   |
+|---------------------|:-----------------------------------:|-------------------------------------------|
+| Variables           |             lower_case              | `delta_time = 0`, `player_age = 18`       |
+| Local variables     |             lower_case              | `player_position = Vector2(0, 0)`         |
+| Global variables    |             lower_case              | `window_ready = False`                    |
+| Constants variables |              ALL_CAPS               | `MAX_VALUE = 8`, `SCREEN_WIDTH = 800`     |
+| Definitions values  |              ALL_CAPS               | `MAX_BUILDINGS = 5`[^1]                   |
+| string values       |              always ""              | `output = "Hello"`, `"welcome"`           |
+| float values        |             always x.x              | `gravity = 10.0`                          |
+| Operators           |           value1 * value2           | `product = value * 6`                     |
+| Operators           |           value1 / value2           | `division = value / 4`                    |
+| Operators           |           value1 + value2           | `sum = value + 10`                        |
+| Operators           |           value1 - value2           | `res = value - 5`                         |
+| Class               |              TitleCase              | `class TextureFormat`                     |
+| Enum Class members  |              ALL_CAPS               | `PIXELFORMAT_UNCOMPRESSED_R8G8B8`         |
+| Class members       |              lowerCase              | `texture.width`, `color.r`                |
+| Functions           |    lowerCase & wordSeparationBy_    | `init_window()`, `update_camera_center()` |
+| Functions params    |              lowerCase              | `width`, `height`                         |
+| Ternary Operator    | result1 if condition else result2 | `print("yes" if value == 0 else "no")`  |
+[^1] like `macro definitions` of value in C
+
+Some other conventions to follow:
+ - **ALWAYS** initialize all defined variables.
+ - **use TABS / 4 spaces**.
+ - Avoid trailing spaces, please, avoid them
+ - Avoid using **semicolon** as you can
+ - Control flow statements always are followed **by a space**:
+```python
+if condition : value = 0
+
+while not window_should_close():
+    #Do something here!
+
+for i in range(NUM_VALUES): print(i)
+```
+ - All conditions checks are **always between parenthesis** but not boolean values:
+```python
+if value > 1 and value1 < 50 and valueActive:
+    #Do something here!
+```
+
+**If proposing new functions, please try to use a clear naming for function-name and functions-parameters, in case of doubt, open an issue for discussion.**
+
+## Import libraries and Module 
+ - import libraries with the form `from library import *`
+ - import modules/variables from libraries with the form `from library import (module1, ..., variable1, ...)`
+```python
+from pyray import *
+from raylib.colors import (
+    RAYWHITE,
+    DARKGRAY,
+    ...
+)
+```
+
+## Files and Directories Naming Conventions
+
+  - Directories will be named using `snake_case`: `resources/models`, `resources/fonts`
+
+  - Files will be named using `snake_case`: `main_title.png`, `cubicmap.png`, `sound.wav`
+
+_NOTE: Avoid any space or special character in the files/dir naming!_
+
+## Games/Examples Directories Organization Conventions
+
+ - Data files should be organized by context and usage in the game, think about the loading requirements for data and put all the resources that need to be loaded at the same time together.
+ - Use descriptive names for the files, it would be perfect if just reading the name of the file, it was possible to know what is that file and where fits in the game.
+ - Here is an example, note that some resources require to be loaded all at once while other require to be loaded only at initialization (gui, font).
+
+```
+resources/audio/fx/long_jump.wav
+resources/audio/music/main_theme.ogg
+resources/screens/logo/logo.png
+resources/screens/title/title.png
+resources/screens/gameplay/background.png
+resources/characters/player.png
+resources/characters/enemy_slime.png
+resources/common/font_arial.ttf
+resources/common/gui.png
+```
+
+## Example Conventions For Python API
+ - examples ***should*** have the following structure
+```python
+"""
+
+raylib [raylib module] example - Name Of The Example
+
+"""
+
+# Import
+# ------------------------------------------------------------------------------------
+# Do something here!
+# ------------------------------------------------------------------------------------
+
+# Definitions
+# ------------------------------------------------------------------------------------
+# Define you functions/global variables here
+# ------------------------------------------------------------------------------------
+
+# Program main entry point
+# ------------------------------------------------------------------------------------
+def main():
+    # Initialization
+    # ------------------------------------------------------------------------------------
+    # Do something here!
+    # ------------------------------------------------------------------------------------
+
+    # Main game loop
+    while ... :  
+        # Update
+        # ----------------------------------------------------------------------------------
+        # Do something here!
+        # ----------------------------------------------------------------------------------
+
+        # Draw
+        # ----------------------------------------------------------------------------------
+        # Do something here!
+        # ----------------------------------------------------------------------------------
+
+    # De-Initialization
+    # ----------------------------------------------------------------------------------
+    # Do something here!
+    # ----------------------------------------------------------------------------------
+
+# Execute the main function 
+if __name__ == '__main__':
+    main()
+```
+ - temple (basic window example):
+```python
+"""
+
+raylib [core] example - Basic Window
+
+"""
+
+# Import
+# ------------------------------------------------------------------------------------
+from pyray import *
+# ------------------------------------------------------------------------------------
+
+# ------------------------------------------------------------------------------------
+# Program main entry point
+# ------------------------------------------------------------------------------------
+def main():
+    # Initialization
+    # ------------------------------------------------------------------------------------
+    SCREEN_WIDTH = 800
+    SCREEN_HEIGHT = 450
+
+    init_window(SCREEN_WIDTH, SCREEN_HEIGHT, "raylib [core] example - basic window")
+
+    # TODO: Load resources / Initialize variables at this point
+
+    set_target_fps(60)  # Set our game to run at 60 frames-per-second
+    # ------------------------------------------------------------------------------------
+
+    # Main game loop
+    while not window_should_close():  # Detect window close button or ESC key
+        # Update
+        # ----------------------------------------------------------------------------------
+        # TODO: Update variables / Implement example logic at this point
+        # ----------------------------------------------------------------------------------
+
+        # Draw
+        # ----------------------------------------------------------------------------------
+        begin_drawing()
+
+        clear_background(RAYWHITE)
+        draw_text("Congrats! You created your first window!", 190, 200, 20, LIGHTGRAY)
+
+        end_drawing()
+        # ----------------------------------------------------------------------------------
+
+    # De-Initialization
+    # ----------------------------------------------------------------------------------
+
+    # TODO: Unload all loaded resources at this point
+
+    close_window()  # Close window and OpenGL context
+    # ----------------------------------------------------------------------------------
+
+
+# Execute the main function 
+if __name__ == '__main__':
+    main()
+
+```