X-Git-Url: https://git.p6c8.net/jirafeau.git/blobdiff_plain/fe04c76a34666ee174a07cc4a1194f27f4b7d547..e975043619b62621781b9adcfb1a55f58ebd257c:/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67bd4b9..5aa918b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,39 +1,98 @@ +# Contributing + Hi, -This document is only made for newcomers in Jirafeau who are digging into -the code. +this document is made for newcomers in Jirafeau who are digging into the code. + +If you have further questions, then just ask for help ð¤. + +## General principle + +Jirafeau is made in the [KISS](http://en.wikipedia.org/wiki/KISS_principle) way (Keep It Simple, Stupid). + +It is meant to be a simple filehosting service, simple to use, simple to install, simple to maintain. + +This project won't evolve to a file manager and will focus to keep a very few dependencies. + +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. + +## Structure Here is a little explaination of Jirafeau's arboresence in a simplified view only to show the most importants files and their role. +``` . -âââ admin.php : adminitration interface, also permits to download files +âââ admin.php : administration interface to manage links and files +âââ docker : folder containing some configuration files to run Jirafeau in docker âââ f.php : permits to download files or show the download page -âââ index.php : only provide a html/javascript client to interact with API -âââ script.php : API interface and it's html documentation +âââ index.php : provides a web interface to interact with API +âââ script.php : API interface (all file actions happen here - upload, deletion, etc) âââ install.php : installation script -âââ tos.php : terms of use the user may edit +âââ tos.php : "Terms of Service" page âââ lib -â  âââ config.local.php : user's parameters -â  âââ config.original.php : default parameters with their documentation -â  âââ functions_*.js : javascript functions for html/javascript client -â  âââ functions.php : core functions and tools of jirafeau -â  âââ locales : langage folder, contain all langage files +â  âââ config.original.php : default parameters +â  âââ config.local.php : the users parameters (auto generated, not versionized) +â  âââ functions_*.js : JavaScript functions for index.php (AJAX etc) +â  âââ functions.php : core functions and tools of Jirafeau +â  âââ tos.original.txt : default text show on the ToS page +â  âââ tos.local.txt : a users alternative text show on the ToS page (not versionized) +â  âââ settings.php : core settings of Jirafeau, includes the configuration params automatically +â  âââ locales : language folder, contains all language files â  âââ template -â  âââ footer.php -â  âââ header.php +â  âââ footer.php : footer with links to source and ToS for all HTML views +â  âââ header.php : header with logo and title for all HTML views âââ media : folder containing all skins -âââ var-xxxxxxx : folder containing all data - âââ async : chunks of uploaded files - âââ files : all files that has been successfully uploaded - âââ links : all links pointing to files with meta-informations +âââ var-xxxxxxx : the users folder containing all data (auto generated, not versionized) + âââ async : chunks of uploaded files (not succressfull yet) + âââ files : all files that have been uploaded successfully + â âââ [hashed file name] : the original file + â âââ [hashed file name]_count : count many links to this file exist + âââ links : all links, including meta-informations, pointing to files + âââ [link] : the link file, includes which original file should be used and some meta data like creation date, expiration time +``` + +## Translations + +Translation may be add via [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/). + +## Coding style + +- This project follows the [PSR-2](http://www.php-fig.org/psr/psr-2/) Coding Style +- Files must be in UTF-8 without BOM and use Unix Line Endings (LF) + +## Branches + +* ```master``` = latest release, e.g. 2.0.1 +* ```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. +* ```test``` = sandbox branch to test new features or merge requests, or run integration tests. The content of this branch may change at any time. + +## Merge Requests + +Please create one branch for each feature and send one merge request for each branch. + +Dont squash several changes or commits into one merge request as this is hard to review. + +Please use ```next-release``` as base branch and send your merge request to this branch (not ```master```). -Coding style: +Quick walktrough: -- PHP function keywords are alone on a line -- Braces "{" must are put in a new line -- Files must be in UTF-8 (without BOM) -- Uses LF (\n) for end of lines +* Create ticket for new feature +* Fork the original repository, clone the own repository, add the original repository as upstream +* Checkout »next-release« branch ```git checkout next-release``` +* Create a new branch on top of that one, e.g. »some-feature« ```git checkout -b some-feature``` +* Commit changes â push â send merge request ```git add -A; git commit; git push``` MR via GitLab (link shown in console) +* Feature is reviewed + * MR accepted: Reviewer checks out »next-release« branch and cherry-picks the commit ```git checkout next-release; git cherry-pick be4369641; git push``` + * 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``` -The whole project is not clean about that, feel free to fix :) +## New Releases +* Compare the [»next-release« branch to »master«](https://gitlab.com/mojo42/Jirafeau/compare/master...next-release) +* Add a list of noteworthy features and bugfixes to the README +* Change the version, using [semantic versioning](http://semver.org/), in ```settings.php``` +* Merge »next-release« branch to »master« +* Update the demo page +* Tag the »master« with the new version +* Push branch and tag +* Dance a little