doc/Developers-Intro.md

   1 # Where to get started to help improve Friendica
   2
   3 <!-- markdownlint-disable MD010 MD013 -->
   4
   5 * [Home](help)
   6
   7 Do you want to help us improve Friendica?
   8 Here we have compiled some hints on how to get started and some tasks to help you choose.
   9 A project like Friendica is the sum of many different contributions.
  10 **Very different skills are required to make good software, not all of them involve coding!**
  11 We are looking for helpers in all areas, whether you write text or code, whether you spread the word to convince people or design new icons.
  12 Whether you feel like an expert or like a newbie - join us with your ideas!
  13
  14 ## Contact us
  15
  16 The discussion of Friendica development takes place in the following Friendica forums:
  17
  18 * The main [forum for Friendica development](https://forum.friendi.ca/profile/developers)
  19
  20 ## Help other users
  21
  22 Remember the questions you had when you first tried Friendica?
  23 A good place to start can be to help new people find their way around Friendica in the [general support forum](https://forum.friendi.ca/prufile/helpers).
  24 Welcome them, answer their questions, point them to documentation or ping other helpers directly if you can't help but think you know who can.
  25
  26 ## Translation
  27
  28 The documentation contains help on how to translate Friendica [at Transifex](/help/translations) where the UI is translated.
  29 If you don't want to translate the UI, or it is already done to your satisfaction, you might want to work on the translation of the /help files?
  30
  31 ## Design
  32
  33 Are you good at designing things?
  34 If you have seen Friendica you probably have ideas to improve it, haven't you?
  35
  36 * If you would like to work with us on enhancing the user interface, please join the [forum for Friendica development](https://forum.friendi.ca/profile/developers).
  37 * Make plans for a better Friendica interface design and share them with us.
  38 * Tell us if you are able to realize your ideas or what kind of help you need.
  39         We can't promise we have the right skills in the group but we'll try.
  40 * Choose a thing to start with, e.g. work on the icon set of your favorite theme
  41
  42 ## Programming
  43
  44 Friendica uses an implementation of [Domain-Driven-Design](help/Developer-Domain-Driven-Design), please make sure to check out the provided links for hints at the expected code architecture.
  45
  46 ### Composer
  47
  48 Friendica uses [Composer](https://getcomposer.org) to manage dependencies libraries and the class autoloader both for libraries and namespaced Friendica classes.
  49
  50 It's a command-line tool that downloads required libraries into the `vendor` folder and makes any namespaced class in `src` available through the whole application through `boot.php`.
  51
  52 If you want to have git automatically update the dependencies with composer, you can use the `post-merge` [git-hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) with a script similar to this one:
  53
  54     #/usr/bin/env bash
  55     # MIT © Sindre Sorhus - sindresorhus.com
  56     # forked by Gianluca Guarini
  57     # phponly by Ivo Bathke ;)
  58     # modified for Friendica by Tobias Diekershoff
  59     changed_files="$(git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD)"
  60     check_run() {
  61                     echo "$changed_files" | grep --quiet "$1" && eval "$2"
  62     }
  63     # `composer install` if the `composer.lock` file gets changed
  64     # to update all the php dependencies
  65     check_run composer.lock "bin/composer.phar install --no-dev"
  66
  67 just place it into `.git/hooks/post-merge` and make it executable.
  68
  69 * [Class autoloading](help/autoloader)
  70 * [Using Composer](help/Composer)
  71 * [How To Move Classes to `src`](help/Developer-How-To-Move-Classes-to-src)
  72
  73 ### Coding standards
  74
  75 For the sake of consistency between contribution and general code readability, Friendica follows the widespread [PSR-2 coding standards](http://www.php-fig.org/psr/psr-2/) to the exception of a few rules.
  76 Here's a few primers if you are new to Friendica or to the PSR-2 coding standards:
  77
  78 * Indentation is tabs, period (not PSR-2).
  79 * By default, strings are enclosed in single quotes, but feel free to use double quotes if it makes more sense (SQL queries, adding tabs and line feeds).
  80 * Operators are wrapped by spaces, e.g. `$var === true`, `$var = 1 + 2` and `'string' . $concat . 'enation'`
  81 * Braces are mandatory in conditions
  82 * Boolean operators are `&&` and `||` for PHP conditions, `AND` and `OR` for SQL queries
  83 * No closing PHP tag
  84 * No trailing spaces
  85 * Array declarations use the new square brackets syntax
  86 * Quoting style is single quotes by default, except for needed string interpolation, SQL query strings by convention and comments that should stay in natural language.
  87
  88 Don't worry, you don't have to know by heart the PSR-2 coding standards to start contributing to Friendica.
  89 There are a few tools you can use to check or fix your files before you commit.
  90
  91 For documentation we use the standard of *one sentence per line* for the `md` files in the `/doc` and `/doc/$lng` subdirectories.
  92
  93 #### Check with [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer)
  94
  95 This tool checks your files against a variety of coding standards, including PSR-2, and ouputs a report of all the standard violations.
  96 You can simply install it through PEAR: `pear install PHP_CodeSniffer`
  97 Once it is installed and available in your PATH, here's the command to run before committing your work:
  98
  99         $> phpcs --standard=ruleset.xml <file or directory>
 100
 101 The output is a list of all the coding standards violations that you should fix before committing your work.
 102 Additionally, `phpcs` integrates with a few IDEs (Eclipse, Netbeans, PHPStorm...) so that you don't have to fiddle with the command line.
 103
 104 #### Fix with PHP Code Beautifier and Fixer (phpbcf) included in PHP Code Sniffer
 105
 106 If you're getting a massive list of standards violations when running `phpcs`, it can be annoying to fix all the violations by hand.
 107 Thankfully, PHP Code Sniffer is shipped with an automatic code fixer that can take care of the tedious task for you.
 108 Here's the command to automatically fix the files you created/modified:
 109
 110         $> phpcbf --standard=ruleset.xml <file or directory>
 111
 112 If the command-line tools `diff` and `patch` are unavailabe for you, `phpcbf` can use slightly slower PHP equivalents by using the `--no-patch` argument.
 113
 114 ### Code documentation
 115
 116 If you are interested in having the documentation of the Friendica code outside of the code files, you can use [Doxygen](http://doxygen.org) to generate it.
 117 The configuration file for Doxygen is located in the base directory of the project sources.
 118 Run
 119
 120         $> doxygen Doxyfile
 121
 122 to generate the files which will be located in the `doc/html` subdirectory in the Friendica directory.
 123 You can browse these files with any browser.
 124
 125 If you find missing documentation, don't hesitate to contact us and write it down to enhance the code documentation.
 126
 127 ### Issues
 128
 129 Have a look at our [issue tracker](https://github.com/friendica/friendica) on github!
 130
 131 * Try to reproduce a bug that needs more inquiries and write down what you find out.
 132 * If a bug looks fixed, ask the bug reporters for feedback to find out if the bug can be closed.
 133 * Fix a bug if you can. Please make the pull request against the *develop* branch of the repository.
 134 * There is a *[Junior Job](https://github.com/friendica/friendica/issues?q=is%3Aopen+is%3Aissue+label%3A"Junior+Jobs")* label for issues we think might be a good point to start with.
 135         But you don't have to limit yourself to those issues.
 136
 137 ### Web interface
 138
 139 The thing many people want most is a better interface, preferably a responsive Friendica theme.
 140 This is a piece of work!
 141 If you want to get involved here:
 142
 143 * Look at the first steps that were made (e.g. the clean theme).
 144         Ask us to find out whom to talk to about their experiences.
 145 * Talk to design people if you know any.
 146 * Let us know about your plans [in the dev forum](https://forum.friendi.ca/profile/developers)
 147         Do not worry about cross-posting.
 148
 149 ### Client software
 150
 151 As Friendica is using a [Twitter/GNU Social compatible API](help/api) any of the clients for those platforms should work with Friendica as well.
 152 Furthermore there are several client projects, especially for use with Friendica.
 153 If you are interested in improving those clients, please contact the developers of the clients directly.
 154
 155 * Android / LinageOS: **Friendiqa** [src](https://git.friendi.ca/lubuwest/Friendiqa)/[Google Play](https://play.google.com/store/apps/details?id=org.qtproject.friendiqa) developed by [Marco R](https://freunde.ma-nic.de/profile/marco)
 156 * iOS: *currently no client*
 157 * SailfishOS: **Friendiy** [src](https://kirgroup.com/projects/fabrixxm/harbour-friendly) - developed by [Fabio](https://kirgroup.com/profile/fabrixxm/profile)
 158 * Windows: **Friendica Mobile** for Windows versions [before 8.1](http://windowsphone.com/s?appid=e3257730-c9cf-4935-9620-5261e3505c67) and [Windows 10](https://www.microsoft.com/store/apps/9nblggh0fhmn) - developed by [Gerhard Seeber](http://mozartweg.dyndns.org/friendica/profile/gerhard/profile)