CONTRIBUTING.md

   1 # Contributing
   2
   3 Hi,
   4
   5 this document is made for newcomers in Jirafeau who are digging into the code.
   6
   7 ## General principle
   8
   9 Jirafeau is made in the [KISS](http://en.wikipedia.org/wiki/KISS_principle) way (Keep It Simple, Stupid).
  10
  11 It is meant to be a simple filehosting service, simple to use, simple to install, simple to maintain.
  12
  13 This project won't evolve to a file manager and will focus to keep a very few dependencies.
  14
  15 So things like a markdown parser for the ToS or E-Mail tasks would be usefull for sure, but may be [rejected](https://gitlab.com/mojo42/Jirafeau/issues/37#note_1191566) since they would a lot of dependencies and makes the project more complex.
  16
  17 ## Structure
  18
  19 Here is a little explaination of Jirafeau's arboresence in a simplified
  20 view only to show the most importants files and their role.
  21
  22 ```
  23 .
  24 ├── admin.php : administration interface to manage links and files
  25 ├── f.php : permits to download files or show the download page
  26 ├── index.php : provides a web interface to interact with API
  27 ├── script.php : API interface (all file actions happen here - upload, deletion, etc)
  28 ├── install.php : installation script
  29 ├── tos.php : "Terms of Service" page
  30 ├── lib
  31 │   ├── config.original.php : default parameters
  32 │   ├── config.local.php : the users parameters (auto generated, not versionized)
  33 │   ├── functions_*.js : JavaScript functions for index.php (AJAX etc)
  34 │   ├── functions.php : core functions and tools of Jirafeau
  35 │   ├── tos.original.txt : default text show on the ToS page
  36 │   ├── tos.local.txt : a users alternative text show on the ToS page (not versionized)
  37 │   ├── settings.php : core settings of Jirafeau, includes the configuration params automatically
  38 │   ├── locales : language folder, contains all language files
  39 │   └── template
  40 │       ├── footer.php : footer with links to source and ToS for all HTML views
  41 │       └── header.php : header with logo and title for all HTML views
  42 ├── media : folder containing all skins
  43 └── var-xxxxxxx : the users folder containing all data (auto generated, not versionized)
  44     ├── async : chunks of uploaded files (not succressfull yet)
  45     ├── files : all files that have been uploaded successfully
  46         ├── [hashed file name] : the original file
  47         ├── [hashed file name]_count : count many links to this file exist
  48     └── links : all links, including meta-informations, pointing to files
  49         ├── [link] : the link file, includes which original file should be used and some meta data like creation date, expiration time
  50 ```
  51
  52 ## Translations
  53
  54 Translation may be add via [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/).
  55
  56 ## Coding style
  57
  58 - This project follows the [PSR-2](http://www.php-fig.org/psr/psr-2/) Coding Style
  59 - Files must be in UTF-8 without BOM and use Unix Line Endings (LF)
  60
  61 ## Branches
  62
  63 * ```master``` = latest release, e.g. 2.0.1
  64 * ```next-release``` = development branch - all new features are merged into this branch until the next version is released. So use this branch as base while developing new features or bugfixes.
  65 * ```test``` = sandbox branch to test new features or merge requests, or run integration tests. The content of this branch may change at any time.
  66
  67 ## Merge Requests
  68
  69 Please create one branch for each feature and send one merge request for each branch.
  70
  71 Dont squash several changes or commits into one merge request as this is hard to review.
  72
  73 Please use ```next-release``` as base branch and send your merge request to this branch (not ```master```).