1# Contributing to thirty bees
2thirty bees is an open-source e-commerce solution, forked from PrestaShop. We'd like to encourage everyone to participate in the project, including contributing your own improvements to the source code.
3
4## Procedure
5 In order to contribute to this project, you need to be familiar with Git, an open source version control system used extensively by thirty bees developers, as well as GitHub:
6 - A nice tutorial about Git can be found here: https://try.github.io/
7 - GitHub help: https://help.github.com/
8
9 Contributing to this project via Git can be done as follows:
10 - Fork this project to your own GitHub account
11 - Recursively clone this project to your local machine (use e.g. `git clone git@github.com:username/ThirtyBees.git --recursive`)
12 - Optionally install the dependencies of this project to test it on your local machine (`composer install` in the root directory)
13 - Create your own local branch (`git checkout -b mybranch`)
14 - Make your changes
15 - Commit (`git commit -m "Commit message"`). We do not have a commit message norm, but do make sure you use the [present tense](https://en.wikipedia.org/wiki/Present_tense)!
16 - Then push the commit to your own fork (`git push -u origin mybranch`)
17 - Visit either the fork or the thirty bees repository and GitHub should ask you to make a pull request. Follow this procedure and wait for one of our developers to include your changes into the codebase or tell you about possible improvements your pull request might need.
18
19 That's it. Thank you for your contribution!
20
21## Coding standards
22 We like to aim for a very high quality open source e-commerce platform. This means that we need to implement high quality standards, guidelines and coding styles that should be used by everyone participating in the project, at all times. Not abiding by the project's coding standards may be a reason to decline your contribution, so be sure to read this section in order to maximize the chance of your changes to land in thirty bees' codebase.
23 The majority of thirty bees is written in PHP, but in our codebase you will also find JavaScript, HTML, CSS, Smarty templates, SQL, XML and JSON. For these languages we use the following code standards:
24 - PHP: [Symfony Standards](http://symfony.com/doc/current/contributing/code/standards.html) PLUS [shorthand aligned arrays](https://github.com/thirtybees/ThirtyBees/blob/de63e54d405c6e3c4660a846684937868838732f/classes/Address.php#L122-L149) MINUS [yoda conditions](https://en.wikipedia.org/wiki/Yoda_conditions)
25 - JavaScript: [Airbnb JavaScript style](https://github.com/airbnb/javascript)
26 - HTML, XML, CSS and Smarty templates: [Mark Otto's coding standards](http://codeguide.co/)
27 - SQL: See [SQL Guidelines](#sql-guidelines) below
28 - JSON: [Google JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml)
29
30### SQL Guidelines
31#### Table names
321. Table names must begin with thirty bees' `_DB_PREFIX_` prefix.
332. Table names must have the same name as the object they reflect: `ps_cart` (replace `ps_` with your own prefix).
343. Table names are singular: `ps_order`
354. Language data has to be stored in a table named exactly like the object's table, but also has the `_lang` suffix: `ps_product_lang`.
365. The same goes for specific shop data. These tables require the `_shop` suffix.
37
38#### SQL Query
391. For simple queries the `DbQuery` class MUST be used:
40    ```php
41    $sql = new DbQuery();
42    $sql->select('p.`name`');
43    $sql->from('product', 'p');
44    $sql->innerJoin('product_lang', 'pl', 'p.`id_lang` = pl.`id_lang`');
45    $sql->where('pl.`id_lang` = 1');
46    ```
47
482. When referring to an `ObjectModel`s primary key or table name, use the escaped `$definition` property:
49    ```php
50    $sql = new DbQuery();
51    $sql->select('p.`'.bqSQL(self::$definition['primary']).'`');
52    $sql->from(bqSQL(self::$definition['table']), 'p');
53    $sql->where('p.`'.bqSQL(self::$definition['primary']).'` = 1');
54    ```
55
563. Keywords in raw db queries must be written in uppercase.
57    ```sql
58    SELECT `firstname`
59    FROM `'._DB_PREFIX_.'customer`
60    ```
61
624. Table aliases have to be named by taking the first letter of each word and must be lowercase:
63    ```php
64    $sql = new DbQuery();
65    $sql->select('p.`'.bqSQL(self::$definition['primary']).'`');
66    $sql->from(bqSQL(self::$definition['table']), 'p');
67    $sql->where('p.`'.bqSQL(self::$definition['primary']).'` = 1');
68    ```
69
705. When conflicts between table aliases occur, the second character also has to be used in the name:
71    ```php
72    $sql = new DbQuery();
73    $sql->select('ca.`'.bqSQL(Product::$definition['primary']).'`, cu.`firstname`');
74    $sql->from(bqSQL(Cart::$definition['table']), 'ca');
75    $sql->innerJoin(bqSQL(Customer::$definition['table']), 'cu', 'ca.`'.bqSQL(Customer::$definition['primary']).'` = cu.`'.Customer::$definition['primary']).'`');
76    ```
77
786. A new line has to be created for each clause in raw db queries:
79    ```php
80    $sql = 'SELECT pl.`name`
81    FROM `'._DB_PREFIX_'.product_lang` pl
82    WHERE pl.`id_product` = 17';
83    ```
84
857. It is forbidden to make a `JOIN` in a `WHERE` clause
86
87## Licenses
88Do not change the license headers of a file, except updating the copyright year.
89Files have either an [Open Software License 3.0 (OSL)](https://tldrlegal.com/license/open-software-licence-3.0) license (Core files) or an [Academic Free License 3.0 (AFL)](https://tldrlegal.com/license/academic-free-license-3.0-(afl)) (module files). If your contribution includes files with a different license your contribution cannot be accepted. If you do need to include a library for your improvement, add it to `composer.json`.
90By contributing to this project, you grant thirty bees a perpetual license on the content you submit to the project. This license implies granting use, modification, improvement, distribution and deletion of your contributions to the administrator of the project. It does not grant you the ability to request the removal of your contributions from the project. Contributing to this project implies that you are the author of the content or that you are authorized by the content author to submit these contributions to thirty bees. If your contributation adds an extra author field, changes the copyright or anything else that changes the software's license, the contribution will be rejected. Instead add your name to the `CONTRIBUTORS.md` file in the changeset. We'd love to add your name to it, after a successful merge!
91