FluidTYPO3: Coding Values

Code of conduct

  1. Respect the work others did before you - suggesting a better solution is always better than complaining.
  2. Respect the opinions of people who comment on your contribution - the changes you make affect many other people and their opinions matter.
  3. Argue logically and objectively if you disagree with a decision.
  4. Help others - if you can help others with the easy parts then we will have more time to help you with the hard parts.

The mandatory stuff

  1. We require English, with no exceptions. In code, comments, issues, pull requests, examples, documentation, ...
  2. We require using a modified version of the TYPO3 coding standards.
  3. We require annotations of all parameters and return types in all PHP code.
  4. We require a specific formatting for all Git commits.
  5. We ship unit tests which all contributions are required to pass. If a test fails it must be adapted and a reason given.

Respecting these five simple rules ensures the formal correctness of contributions.

The nice-to-have stuff

  1. We desire unit tests that cover code additions. If you are able.
  2. We desire full PHP doc comments for each method and class describing usage and behavior.

Also respecting these two additional wishes makes our jobs easier and greatly improves the likelihood of having your contribution accepted (quickly, too).

Coding standards

We use a slightly modified version of the current TYPO3 coding standards - and we update ours as it gets updated. We ship our coding standards in a utility repository:

https://github.com/FluidTYPO3/FluidTYPO3-CodingStandards

The key differences are:

  1. We use Yoda conditions and explicit comparisons, which means that instead of if (!$var) you must write FALSE === $var if the variable is expected to be FALSE.
  2. With almost no exceptions (i.e. unless absolutely required by a piece of code), weak comparisons (==) are not permitted.
  3. We exclusively ship classes that reside in a PHP namespace. Our vendor name is FluidTYPO3.

Respecting the coding standards is the key to consistency and we must have this consistency in order to properly maintain the hundreds of class files we ship.

Git commits

We require a particular format for all git commits:

  1. The commit must start with a valid prefix to help us identify the nature of the change. Valid prefixes are:
    1. [BUGFIX] when the commit fixes a bug
    2. [FEATURE] when the commit adds new capabilities
    3. [DOC] when the commit only touches documentation (README, PHP doc comments, etc)
    4. [TASK] when the commit does not fall into any of the other categories
  2. After the prefix the commit subject must start with an uppercase letter, e.g. [BUGFIX] Fixed problem abc with class xyz.

And the following general considerations apply when you create pull requests:

  1. Do not include merge commits in your pull request. For the best result, keep your work in one branch and use rebase if you must.
  2. Do not make multiple tiny commits about the same feature/bug/change - squash commits instead.
  3. Do not create the pull request until you are positively ready for it to be reviewed. All changes and comments in pull requests cause emails to all team members.
  4. Ask for help with any of these things if you need it.

These few, simple rules are used consistently in every repository's history - any commit or pull request can be used as reference.

Jump to...