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).
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
## Coding style
-- PHP function keywords are alone on a line
-- Braces "{" must be put in a new line
+- 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)
-The whole project is not clean about that yet, feel free to fix :)
+## 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```).
+
+Quick walktrough:
+
+* 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```
+* Make your change
+* 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"`
+* 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```
+
+## New Releases
+
+* If the release is not done for security purposes: create a new issue and freeze next-release branch for at least week.
+* 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 `CHANGELOG.md`
+* Add eventual upgrade procedure to `CHANGELOG.md`
+* 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
+* Build & push new docker image
+* Dance a little
git.p6c8.net / jirafeau_mojo42.git / blobdiff