[GitHub/WoltLab/WCF.git] / CONTRIBUTING.md

CONTRIBUTING
============

First of all: Thanks for your interest in contributing to WoltLab Suite Core! However, you have to meet some requirements in order to get your changes accepted.

**Notice:** This is the development tree of WoltLab Suite Core representing the upcoming version of WoltLab Suite, if you wish to submit pull requests for WSC 3.0.x, please select the branch "3.0". 

General requirements
--------------------
- **API changes are undesirable**, we want to maintain full backwards compatibility to WSC 3.0.x
- Testing is the key, you MUST try out your changes before submitting pull requests. It saves us and yourself a lot of time.
- The code SHOULD be written by yourself, otherwise you have to check the license beforehand with regard to compatibility and give the proper credit to the original author.

Files
-----
- Unix newlines (\n) MUST be used in every file (php, tpl, less, js, etc.)
- All files MUST be saved in ASCII encoding, except language files, which MUST be UTF-8 encoded

Formatting
----------
- Tabs MUST be used for indentation, you HAVE TO use a tab size of 8
    - empty lines MUST be indentated as deep as the previous line
- All identifiers and comments MUST be written in English
- PHP
    - The closing PHP tag MUST be omitted
    - Every file MUST end with a newline character (\n)

Additionally: Have a look at existing files to find out what they should look like.

Automated tests
---------------
We are running [PHP Codesniffer](https://github.com/squizlabs/PHP_CodeSniffer) to ensure most of our formatting rules. You SHOULD test your changes before submitting them with it.

1. Install PHP Codesniffer, either via PEAR or via cloning it
2. Execute the following command in the root of your clone of WoltLab Suite Core:

   ```sh
    $ phpcs -p --extensions=php --standard="`pwd`/CodeSniff/WCF" .
   ```
3. Fix any errors
4. Repeat it until no more errors occur
Commit	Line	Data
f9b320a3 TD	1	CONTRIBUTING
	2	============
	3
e71525e4	4	First of all: Thanks for your interest in contributing to WoltLab Suite Core! However, you have to meet some requirements in order to get your changes accepted.
f9b320a3	5
e068b7c6	6	Notice: This is the development tree of WoltLab Suite Core representing the upcoming version of WoltLab Suite, if you wish to submit pull requests for WSC 3.0.x, please select the branch "3.0".
37111120	7
f9b320a3 TD	8	General requirements
f9b320a3 TD	9	--------------------
e068b7c6	10	- API changes are undesirable, we want to maintain full backwards compatibility to WSC 3.0.x
ed12260e G	11	- Testing is the key, you MUST try out your changes before submitting pull requests. It saves us and yourself a lot of time.
ed12260e G	12	- The code SHOULD be written by yourself, otherwise you have to check the license beforehand with regard to compatibility and give the proper credit to the original author.
f9b320a3 TD	13
	14	Files
	15	-----
	16	- Unix newlines (\n) MUST be used in every file (php, tpl, less, js, etc.)
	17	- All files MUST be saved in ASCII encoding, except language files, which MUST be UTF-8 encoded
	18
	19	Formatting
	20	----------
	21	- Tabs MUST be used for indentation, you HAVE TO use a tab size of 8
0af1095f TD	22	- empty lines MUST be indentated as deep as the previous line
0af1095f TD	23	- All identifiers and comments MUST be written in English
f9b320a3 TD	24	- PHP
	25	- The closing PHP tag MUST be omitted
	26	- Every file MUST end with a newline character (\n)
	27
	28	Additionally: Have a look at existing files to find out what they should look like.
	29
	30	Automated tests
	31	---------------
ed12260e	32	We are running [PHP Codesniffer](https://github.com/squizlabs/PHP_CodeSniffer) to ensure most of our formatting rules. You SHOULD test your changes before submitting them with it.
f9b320a3 TD	33
f9b320a3 TD	34	1. Install PHP Codesniffer, either via PEAR or via cloning it
e71525e4	35	2. Execute the following command in the root of your clone of WoltLab Suite Core:
f9b320a3 TD	36
	37	```sh
	38	$ phpcs -p --extensions=php --standard="`pwd`/CodeSniff/WCF" .
	39	```
	40	3. Fix any errors
ed12260e	41	4. Repeat it until no more errors occur