]> git.p6c8.net - jirafeau_project.git/blobdiff - CONTRIBUTING.md
Add more details about upload error
[jirafeau_project.git] / CONTRIBUTING.md
index 641fb44c18403ace6de893be36eee2206847ecec..71c5b882b00f4bfe8c62b7802f153a7e858202c3 100644 (file)
@@ -4,6 +4,8 @@ Hi,
 
 this document is 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).
 ## General principle
 
 Jirafeau is made in the [KISS](http://en.wikipedia.org/wiki/KISS_principle) way (Keep It Simple, Stupid).
@@ -12,16 +14,17 @@ It is meant to be a simple filehosting service, simple to use, simple to install
 
 This project won't evolve to a file manager and will focus to keep a very few dependencies.
 
 
 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.
+So things like a markdown parser for the ToS or E-Mail tasks would be useful 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
 
 
 ## Structure
 
-Here is a little explaination of Jirafeau's arboresence in a simplified
-view only to show the most importants files and their role.
+Here is a little explanation of Jirafeau's structure in a simplified
+view only to show the most important files and their role.
 
 ```
 .
 β”œβ”€β”€ admin.php : administration interface to manage links and 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 : provides a web interface to interact with API
 β”œβ”€β”€ script.php : API interface (all file actions happen here - upload, deletion, etc)
 β”œβ”€β”€ f.php : permits to download files or show the download page
 β”œβ”€β”€ index.php : provides a web interface to interact with API
 β”œβ”€β”€ script.php : API interface (all file actions happen here - upload, deletion, etc)
@@ -29,38 +32,35 @@ view only to show the most importants files and their role.
 β”œβ”€β”€ tos.php : "Terms of Service" page
 β”œβ”€β”€ lib
 β”‚Β Β  β”œβ”€β”€ config.original.php : default parameters
 β”œβ”€β”€ tos.php : "Terms of Service" page
 β”œβ”€β”€ lib
 β”‚Β Β  β”œβ”€β”€ config.original.php : default parameters
-β”‚Β Β  β”œβ”€β”€ config.local.php : the users parameters (auto generated, not versionized)
+β”‚Β Β  β”œβ”€β”€ config.local.php : the users parameters (auto generated, not versioned)
 β”‚Β Β  β”œβ”€β”€ 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
 β”‚Β Β  β”œβ”€β”€ 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)
+β”‚Β Β  β”œβ”€β”€ tos.local.txt : a users alternative text show on the ToS page (not versioned)
 β”‚Β Β  β”œβ”€β”€ settings.php : core settings of Jirafeau, includes the configuration params automatically
 β”‚Β Β  β”œβ”€β”€ locales : language folder, contains all language files
 β”‚Β Β  β””── template
 β”‚Β Β      β”œβ”€β”€ 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
 β”‚Β Β  β”œβ”€β”€ settings.php : core settings of Jirafeau, includes the configuration params automatically
 β”‚Β Β  β”œβ”€β”€ locales : language folder, contains all language files
 β”‚Β Β  β””── template
 β”‚Β Β      β”œβ”€β”€ 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 : the users folder containing all data (auto generated, not versionized)
-    β”œβ”€β”€ async : chunks of uploaded files (not succressfull yet) 
+└── var-xxxxxxx : the users folder containing all data (auto generated, not versioned)
+    β”œβ”€β”€ async : chunks of uploaded files (not successful yet) 
     β”œβ”€β”€ files : all files that have been uploaded successfully
     β”œβ”€β”€ 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
-        Γ’\94\9c── [link] : the link file, includes which original file should be used and some meta data like creation date, expiration time
+    β”‚   β”œβ”€β”€ [hashed file name] : the original file
+    β”‚   β””── [hashed file name]_count : count many links to this file exist
+    β””── links : all links, including metadata, pointing to files
+        Γ’\94\94── [link] : the link file, includes which original file should be used and some meta data like creation date, expiration time
 ```
 
 ## Translations
 
 ```
 
 ## Translations
 
-Translation may be add via [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/).
+Translation may be added via [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/).
 
 ## Coding style
 
 
 ## 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)
 
 - 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
 ## Branches
 
 * ```master``` = latest release, e.g. 2.0.1
@@ -71,6 +71,34 @@ The whole project is not clean about that yet, feel free to fix :)
 
 Please create one branch for each feature and send one merge request for each branch. 
 
 
 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.
+Don't 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```).
 
 Please use ```next-release``` as base branch and send your merge request to this branch (not ```master```).
+
+Quick walkthrough:
+
+* 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`. Make sure to list all new configuration items.
+* Build and test docker image
+* Change the version, using [semantic versioning](http://semver.org/), in ```settings.php```
+* Merge Β»next-releaseΒ« branch to Β»masterΒ«
+* Tag the Β»masterΒ« with the new version
+* Push branch and tag
+* Push new docker image
+* Update the demo page
+* Dance a little

patrick-canterino.de