|
| 1 | +# Contribution Guidelines for TempusDebugger |
| 2 | +Contributing to TempusDebugger is completely voluntary and should follow all of the guidelines listed here in order to ensure the highest probability of acceptance. It is highly recommended to use a php linter to automate more of this process. The project is maintained on github and all contributions need to be submitted via pull request to their specific repository under the `dev` branch. In order to contribute, simply follow the instructions for [creating a pull request](#creating-a-pull-request) below. |
| 3 | + |
| 4 | +## Pull Request Requirements |
| 5 | +- All revisions must follow TTP naming conventions (see [Naming Conventions](#naming-conventions) Section) |
| 6 | +- Include a clear and concise explanation of the features or changes included in your revision listed by file. |
| 7 | +- All code must follow [PSR 2](http://www.php-fig.org/psr/psr-2/) standards |
| 8 | +- prefer the use of [] for arrays over array() |
| 9 | +- All functions must be documented with the exception of controller methods (see [Documentation](#documentation) Section) |
| 10 | +- Controller methods may be doc-blocked when necessary for clarity (see [Documentation](#documentation) Section) |
| 11 | +- All new Classes must include a class level doc-block (see [Documentation](#documentation) Section) |
| 12 | +- Any new dependencies will have a longer validation process and should be accompanied by the required information (see [Dependencies](#dependencies) Section) |
| 13 | + |
| 14 | +## Naming Conventions |
| 15 | +- File names are to be lower case |
| 16 | +- All class names must be upper case |
| 17 | +- Any data being stored as a file must be saved in the app directory |
| 18 | +- Controllers must have a constructor and destructor incorporating the constructor and destructor in the Resources Controller |
| 19 | +- (This will be an interface requirement soon) |
| 20 | +- Views must be named using underscores for separation and must be prefixed with view_ |
| 21 | + |
| 22 | +## Dependencies |
| 23 | +Whenever a dependency is updated or added, pull requests must include a section that answers the following questions. |
| 24 | +- Why is this dependency required |
| 25 | +- Could this be reasonably accomplished within the app by implementing new features in a later version? explain. |
| 26 | +- What is the latest stable version that can be used |
| 27 | +- What features are absolutely necessary for your feature or modification to work |
| 28 | + |
| 29 | +## Documentation |
| 30 | +### Classes |
| 31 | + |
| 32 | +New classes must be prefaced with a doc-block following this style: |
| 33 | +``` |
| 34 | +/** |
| 35 | + * Controllers/admin.php |
| 36 | + * |
| 37 | + * This is the admin controller. |
| 38 | + * |
| 39 | + * @version 1.0 |
| 40 | + * |
| 41 | + * @author Joey Kimsey <JoeyKimsey@thetempusproject.com> |
| 42 | + * |
| 43 | + * @link https://TheTempusProject.com |
| 44 | + * |
| 45 | + * @license https://opensource.org/licenses/MIT [MIT LICENSE] |
| 46 | + */ |
| 47 | +``` |
| 48 | + |
| 49 | +From top to bottom: |
| 50 | +- Filename on the second line |
| 51 | +- A description for the file |
| 52 | +- The TTP version this file was built for |
| 53 | +`@version 1.0` |
| 54 | +- The Authors name or alias and email |
| 55 | +`@author first last <email@link.com>` |
| 56 | +- A copy of the MIT license |
| 57 | +`@license https://opensource.org/licenses/MIT [MIT LICENSE]` |
| 58 | +- May include a link for more information |
| 59 | +`@link http://link.com` |
| 60 | + |
| 61 | +### Functions |
| 62 | +Functions must be prefaced with a doc-block following this style: |
| 63 | +``` |
| 64 | +/** |
| 65 | + * Intended as a self-destruct session. If the specified session does not |
| 66 | + * exist, it is created. If the specified session does exist, it will be |
| 67 | + * destroyed and returned. |
| 68 | + * |
| 69 | + * @param string $name - Session name to be created or checked |
| 70 | + * @param string $string - The string to be used if session needs to be |
| 71 | + * created. (optional) |
| 72 | + * |
| 73 | + * @return bool|string - Returns bool if creating, and a string if the |
| 74 | + * check is successful. |
| 75 | + */ |
| 76 | +``` |
| 77 | + |
| 78 | +From top to bottom: |
| 79 | +- There must be a description of the functions intended usage on the second line |
| 80 | +- All parameters should be documented like this |
| 81 | +`@param [type] $name - description` |
| 82 | +- Any function with a return statement must also be documented as such |
| 83 | +`@return [type] - description` |
| 84 | + |
| 85 | +## Creating a Pull Request |
| 86 | +This is a simple explanation of how to create a pull request for changes to TempusDebugger. You can find a detailed walk-through on how to [create a pull request](https://help.github.com/articles/creating-a-pull-request/) on github. |
| 87 | + |
| 88 | +1. First ensure you have followed all the contributing guidelines |
| 89 | +2. Squash your merge into a single revision. This will make it easier to view the changes as a whole. |
| 90 | +3. You can submit a pull request [here](https://github.com/TheTempusProject/TempusDebugger/compare) |
| 91 | +4. Please submit all pull requests to the dev branch or they will be ignored. |
0 commit comments