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 If you have further questions, then just ask for help 🤓.
   8
   9 ## General principle
  10
  11 Jirafeau is made in the [KISS](http://en.wikipedia.org/wiki/KISS_principle) way (Keep It Simple, Stupid).
  12
  13 It is meant to be a simple filehosting service, simple to use, simple to install, simple to maintain.
  14
  15 This project won't evolve to a file manager and will focus to keep a very few dependencies.
  16
  17 So things like a markdown parser for the ToS or E-Mail tasks would be useful for sure, but were [rejected](https://gitlab.com/mojo42/Jirafeau/issues/37#note_1191566) long ago since they would add a lot of dependencies and makes the project more complex.
  18
  19 ## Structure
  20
  21 Here is a little explanation of Jirafeau's structure in a simplified
  22 view only to show the most important files and their role.
  23
  24 ```
  25 .
  26 ├── admin.php : administration interface to manage links and files
  27 ├── docker : folder containing some configuration files to run Jirafeau in docker
  28 ├── f.php : permits to download files or show the download page
  29 ├── index.php : provides a web interface to interact with API
  30 ├── script.php : API interface (all file actions happen here - upload, deletion, etc)
  31 ├── install.php : installation script
  32 ├── tos.php : "Terms of Service" page
  33 ├── lib
  34 │   ├── config.original.php : default parameters
  35 │   ├── config.local.php : the users parameters (auto generated, not versioned)
  36 │   ├── functions_*.js : JavaScript functions for index.php (AJAX etc)
  37 │   ├── functions.php : core functions and tools of Jirafeau
  38 │   ├── tos.original.txt : default text show on the ToS page
  39 │   ├── tos.local.txt : a users alternative text show on the ToS page (not versioned)
  40 │   ├── settings.php : core settings of Jirafeau, includes the configuration params automatically
  41 │   ├── locales : language folder, contains all language files
  42 │   └── template
  43 │       ├── footer.php : footer with links to source and ToS for all HTML views
  44 │       └── header.php : header with logo and title for all HTML views
  45 ├── media : folder containing all skins
  46 └── var-xxxxxxx : the users folder containing all data (auto generated, not versioned)
  47     ├── async : chunks of uploaded files (not successful yet)
  48     ├── files : all files that have been uploaded successfully
  49     │   ├── [hashed file name] : the original file
  50     │   └── [hashed file name]_count : count many links to this file exist
  51     └── links : all links, including metadata, pointing to files
  52         └── [link] : the link file, includes which original file should be used and some meta data like creation date, expiration time
  53 ```
  54
  55 ## Translations
  56
  57 Translation may be added via [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/).
  58
  59 ## Coding style
  60
  61 - This project follows the [PSR-2](http://www.php-fig.org/psr/psr-2/) Coding Style
  62 - Files must be in UTF-8 without BOM and use Unix Line Endings (LF)
  63
  64 ## Branches
  65
  66 * `master` = latest release, e.g. 2.0.1
  67 * `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.
  68 * `test` = sandbox branch to test new features or merge requests, or run integration tests. The content of this branch may change at any time.
  69
  70 ## Merge Requests
  71
  72 Please create one branch for each feature and send one merge request for each branch.
  73
  74 Don't squash several changes or commits into one merge request as this is hard to review.
  75
  76 Please use `next-release` as base branch and send your merge request to this branch (not `master`).
  77
  78 Quick walkthrough:
  79
  80 * Create ticket for new feature
  81 * Fork the original repository, clone the own repository, add the original repository as upstream
  82 * Checkout `next-release` branch `git checkout next-release`
  83 * Create a new branch on top of that one, e.g. `some-feature`: `git checkout -b some-feature`
  84 * Make your change
  85 * You may check if the project is still [REUSE Compliant](https://reuse.software/) by running `docker run -v $(pwd):/code --rm fsfe/reuse /bin/sh -c "cd /code && reuse lint"`
  86 * Commit changes → push → send merge request `git add -A; git commit; git push` MR via GitLab (link shown in console)
  87 * Feature is reviewed
  88   * MR accepted: Reviewer checks out `next-release` branch and cherry-picks the commit `git checkout next-release; git cherry-pick be4369641; git push`
  89   * MR declined: Reviewer add some notes, Developer rebases his branch, adds neccessary changes, force pushes the branch, ask a reviewer to review the changes in the merge request ticket (as Gitlab recognizes them automatically) `git checkout some-feature; git rebase upstream/next-release` …[add changes]… `git add -A, git commit --amend; git push -f`
  90
  91 ## New Releases
  92
  93 * Fetch weblate and rebase and import translations
  94 * If the release is not done for security purposes: create a new issue and freeze next-release branch for at least week.
  95 * Compare the [`next-release` branch to `master`](https://gitlab.com/jirafeau/Jirafeau/compare/master...next-release)
  96 * Add a list of noteworthy features and bugfixes to `CHANGELOG.md`
  97 * Add eventual upgrade procedure to `CHANGELOG.md`. Make sure to list all new configuration items.
  98 * Build and test docker image
  99 * Change the version, using [semantic versioning](http://semver.org/), in `settings.php`
 100 * Merge `next-release` branch to `master`
 101 * Tag the `master` with the new version
 102 * Push branch and tag
 103 * Push new docker image
 104 * Update the demo page
 105 * Dance a little