Sourcecode of the Spootle Jirafeau instance
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This repo is archived. You can view files and clone it, but cannot push or open issues/pull-requests.
 
 
 
 

5.7 KiB

Contributing

Hi,

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 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 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 : 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)
├── install.php : installation script
├── tos.php : "Terms of Service" page
├── lib
│   ├── 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 : 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) 
    ├── 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.

Coding style

  • This project follows the 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).

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 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.
  • Make sure to run php-cs-fixer fix --rules=@PSR2 . and commit.
  • Compare the »next-release« branch to »master«
  • Add a list of noteworthy features and bugfixes to CHANGELOG.md
  • Add eventual upgrade procedure to CHANGELOG.md
  • Build and test docker image
  • Change the version, using semantic versioning, 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