hortusfox-web/CONTRIBUTING.md

Contribution Guidelines

Table of Contents

• Overview
• Framework
• Localization
• Docker

Overview

These guidelines provide information on the best practices on how to contribute to this repository. Following this guidelines will fasten the review of pull requests.

The following rules for pull requests apply:

• Create an issue for your PR
• Only one PR for a specific issue
• Do not commit unrelated code to your PR
• Provide specific explanations about your PR
• Using descriptive commit messages is mandatory
• Follow the existing style of code
• Code that is generated by AI services will be rejected
• If required, provide answers to possible questions

Contributions must comply with open-source definitions and need to be compatible with the projects license. Also some principles of self-hosted must be respected. These include (but are not limited to) data privacy.

If you have any questions before submitting a PR, you can first create an issue to get answers.

Framework

HortusFox is built with the Asatru PHP Framework. The documentation is located in the /doc directory. There is also an online documentation available.

Localization

Submitting new localizations helps to bring the project to a broader audience. Language files are located in the /app/lang directory.

All localizations must meet the following requirements

• Comment headers need to stay in english
• Comment headers need to contain the language name
• Language identifiers must comply with ISO_639-1
• Some phrases may not be translated, but must remain in english (e.g. names of products, services or platforms)

Steps to create a new language

1. Create a new folder with your language and add the following files (copy them from /app/en). As an example we use de as german language.

/app/lang/de/app.php
/app/lang/de/errors.php
/app/lang/de/tb.php

2. Translate the original phrases into your desired language. Note that expressions in moustache-brackets are placeholders for variables.

return [
    //...
    'some_expression' => 'Here comes the translated phrase',
    'another_expression' => 'The following expression is a variable placeholder: {var}.'
    //...
];

Users can now select the new language via their preferences and you can also set the language as default in the admin dashboard.

Note: Pull requests of missing translations are appreciated. Please tag the associated issue of your pull request with the localization tag.

Docker

The primary purpose of this project is the HortusFox app, so only a minimal Docker setup is provided. Since there are many specific use cases and deployment tools, the project cannot reasonably support all of them. You are welcome to expand on the current Docker setup for your own needs, but pull requests with changes specific to Docker will be rejected unless they address security vulnerabilities or bug fixes.