CONTRIBUTING.md

Contributing

It's great you want to contribute to this project. You can do this in many ways, so keep on reading. 😃 🎉

Bug reporting (Issues)

If you experience any issues you can use the GitHubs Issue Tracker to report these. Please include the following details:

• Operation system
• PHP version
• XenForo version
• version of this add-on
• whether you installed libsodium and if so:
  • which version of libsodium you installed
• cURL version if relevant (if you experience connection/sending errors)
• any settings, which may influence the issue you have

An issue template will be shown when you create a new issue in this repo.

If you are not the server admin and your error happened on a publicy available server you can also just share the link to the forum. However, please make sure to contact the server admin before, to make sure the issue cannot be solved by him/her.

Translating

The language files can be found in xenforo-threema-gateway\languages. If there is a language missing which you like to be supported, feel free to translate it. You can use the English example as a starting point. It is recommend to use XenForo for this as you can use the internal XenForo translation system, but as these are just XML files so you can also manually translate them.

Special notes for some languages:

• German: Place the verb last, so say "Modus aktivieren" instead of "Aktiviere Modus".

Coding

Here are some rules you should follow when you want to contribute code to this repo.

Commit messages

• Use the present tense ("Add feature" not "Added feature")
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")

More information: A Note About Git Commit Messages

PHP Style

Use the PHP Coding Style Fixer to clean up your code. There is a config file for this tool included in the repo (.php_cs), where many styling rules will be applied automatically. If you do not want or can use this, please follow these rules:

• Follow all rules, which are marked as PSR-0, PSR-1 and PSR-2 on the php cs fixer site. This are basic rules and should not be too difficult.
• Additionally follow these rules:
  • concat_with_spaces Around an . should be one space at each side.
  • short_array_syntax Use the new short array syntax of PHP 5.4
  • standardize_not_equal Use != instead of <>
  • operators_spaces All operators should have one space at each side.
  • duplicate_semicolon Do not duplicate semicolons.
  • single_array_no_trailing_comma Single-line arrays should have no comma.
  • print_to_echo Do not use print. Use echo instead.
  • single_quote Prefer single quotes over double quotes.

Additionally there some other rules:

• Use PHPdoc

• Also use PHPDOC for all new variables you introduce: /** @var string $someString This string is an example. */

• Do not require a higher PHP version as described in the current system requirements without prior discussing this. Actually I think the current required PHP version is already quite high, so you should be able to use most of the nice features of recent PHP versions.

• Test your changes! (except when you only edit the documentation)

• use camelCase for variable and function names

• start any new file like this:

  <?php
  /**
   * Short description of the purpose of this file.
   *
   * More information if required.
   *
   * @package ThreemaGateway
   * @author rugk
   * @copyright Copyright (c) rugk, 2017
   * @license MIT/Expat license, see LICENSE.md for details
   */

• When adding a regular expression add a link to a sample/test set on https://regex101.com/ in the comments. When modifying the RegExp edit this test set and update the link.

MySQL

• Always use prepared statements.
• Use Zend_Db - that's how XenForo does it.

JavaScript/jQuery

• We use the extensible module pattern, which is a variation of the popular Revealing Module Pattern. Please follow the style shown in the already existing JS files.

XenForo

• Intend templates correctly with tabs.
• Avoid direct MySQL queries. Use Models/DataWriters instead.