]> git.p6c8.net - jirafeau_project.git/blob - CONTRIBUTING.md
Merge remote-tracking branch 'origin/master'
[jirafeau_project.git] / 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 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.
18
19 ## Structure
20
21 Here is a little explaination of Jirafeau's arboresence in a simplified
22 view only to show the most importants files and their role.
23
24 ```
25 .
26 ├── admin.php : administration interface to manage links and files
27 ├── f.php : permits to download files or show the download page
28 ├── index.php : provides a web interface to interact with API
29 ├── script.php : API interface (all file actions happen here - upload, deletion, etc)
30 ├── install.php : installation script
31 ├── tos.php : "Terms of Service" page
32 ├── lib
33 │   ├── config.original.php : default parameters
34 │   ├── config.local.php : the users parameters (auto generated, not versionized)
35 │   ├── functions_*.js : JavaScript functions for index.php (AJAX etc)
36 │   ├── functions.php : core functions and tools of Jirafeau
37 │   ├── tos.original.txt : default text show on the ToS page
38 │   ├── tos.local.txt : a users alternative text show on the ToS page (not versionized)
39 │   ├── settings.php : core settings of Jirafeau, includes the configuration params automatically
40 │   ├── locales : language folder, contains all language files
41 │   └── template
42 │   ├── footer.php : footer with links to source and ToS for all HTML views
43 │   └── header.php : header with logo and title for all HTML views
44 ├── media : folder containing all skins
45 └── var-xxxxxxx : the users folder containing all data (auto generated, not versionized)
46 ├── async : chunks of uploaded files (not succressfull yet)
47 ├── files : all files that have been uploaded successfully
48 ├── [hashed file name] : the original file
49 ├── [hashed file name]_count : count many links to this file exist
50 └── links : all links, including meta-informations, pointing to files
51 ├── [link] : the link file, includes which original file should be used and some meta data like creation date, expiration time
52 ```
53
54 ## Translations
55
56 Translation may be add via [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/).
57
58 ## Coding style
59
60 - This project follows the [PSR-2](http://www.php-fig.org/psr/psr-2/) Coding Style
61 - Files must be in UTF-8 without BOM and use Unix Line Endings (LF)
62
63 ## Branches
64
65 * ```master``` = latest release, e.g. 2.0.1
66 * ```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.
67 * ```test``` = sandbox branch to test new features or merge requests, or run integration tests. The content of this branch may change at any time.
68
69 ## Merge Requests
70
71 Please create one branch for each feature and send one merge request for each branch.
72
73 Dont squash several changes or commits into one merge request as this is hard to review.
74
75 Please use ```next-release``` as base branch and send your merge request to this branch (not ```master```).
76
77 Quick walktrough:
78
79 * Create ticket for new feature
80 * Fork the original repository, clone the own repository, add the original repository as upstream
81 * Checkout »next-release« branch ```git checkout next-release```
82 * Create a new branch on top of that one, e.g. »some-feature« ```git checkout -b some-feature```
83 * Commit changes → push → send merge request ```git add -A; git commit; git push``` MR via GitLab (link shown in console)
84 * Feature is reviewed
85 * MR accepted: Reviewer checks out »next-release« branch and cherry-picks the commit ```git checkout next-release; git cherry-pick be4369641; git push```
86 * 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```
87
88 ## New Releases
89
90 * Compare the [»next-release« branch to »master«](https://gitlab.com/mojo42/Jirafeau/compare/master...next-release)
91 * Add a list of noteworthy features and bugfixes to the README
92 * Change the version, using [semantic versioning](http://semver.org/), in ```settings.php```
93 * Merge »next-release« branch to »master«
94 * Update the demo page
95 * Tag the »master« with the new version
96 * Push branch and tag
97 * Dance a little

patrick-canterino.de