jjsm01/kimai2
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

various documentation updates (#176)

Browse Source 
* updated README
* improved CONTRIBUTING guidelines
* improved wording on developer docu
This commit is contained in:
Kevin Papst
2018-06-23 21:20:20 +02:00
committed by GitHub
parent e9e61afc76
commit c3251ee435
4 changed files with 62 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
.editorconfig Normal file
View File

@@ -0,0 +1,10 @@
; top-most EditorConfig file
root = true
; Unix-style newlines
[*]
end_of_line = LF
[*.php]
indent_style = space
indent_size = 4

38
CONTRIBUTING.md
View File

@@ -1,16 +1,17 @@
# Contributing
The Kimai application is an open source project. Contributions made by the community are welcome.
Kimai is an open source project, contributions made by the community are welcome.
Send us your ideas, code reviews, pull requests and feature requests to help us improve this project.
## Pull request rules
- We use PSR-2 with some addons code styles (check our [php-cs-fixer config](.php_cs.dist)), run `bin/console kimai:phpcs` to verify and `bin/console kimai:phpcs --fix` to fix violations
- Add PHPUnit tests for your changes, verify everything still works and execute our test-suites `bin/console kimai:test-unit` and `bin/console kimai:test-integration`
- If you contribute new files, please add them with the file-header template from below
- With sending in a PR, you accept that your contributions/code will be published under MIT license (see the LICENSE file as well)
- If one of the checks fail, please fix them before asking for a review
- We use PSR-2 with some additional code-style checks (see our [php-cs-fixer config](.php_cs.dist)). You can run `bin/console kimai:phpcs` to check and `bin/console kimai:phpcs --fix` to fix violations.
- Add PHPUnit tests for your changes, verify everything still works and execute our test-suites `bin/console kimai:test-unit` and `bin/console kimai:test-integration`.
- If you contribute new files, please add them with the file-header template from below (our chode-style fixer can do that for you).
- With sending in a PR, you accept that your contributions/code will be published under MIT license (see the [LICENSE](LICENSE) file as well).
- If one of the PR checks fails, please fix them before asking us for a review.
Further documentation can be found in the [developer documentation](var/docs/developers.md).
### File-header template
```
@@ -22,26 +23,3 @@ Send us your ideas, code reviews, pull requests and feature requests to help us
*/
```
## Translations
We try to keep the number of language files small to make it easier to identify the location for your new messages.
- If you add a new key, you have to add it in every language file
- Its very likely that you want to edit the file `messages` as it holds 90% of our application translations
The files in a quick overview:
- `AvanzuAdminTheme` is only meant for translating strings from the original theme
- `exceptions` only holds translations of error pages and exception handlers
- `flashmessages`
- `messages` holds most of the visible application translations
- `pagerfanta` includes the translations for the pagination component
- `sidebar` holds all the translations of the right sidebar
- `validators` only hold translations related to violations/validation of submitted form data (or API calls)
## Documentation
The documentation is in [var/docs/](var/docs/) and its available both at GitHub and in your running Kimai instance.
- Please verify that all links work in your Kimai instance before submitting

26
README.md
View File

@@ -1,6 +1,6 @@
# Kimai v2 - Time Tracking
Kimai v2 - the open source time-tracking application with a mobile-first approach.
Kimai v2 - the open source time-tracking application with a mobile-first approach, read more at the [official website](http://v2.kimai.org).
[![Travis Status](https://travis-ci.org/kevinpapst/kimai2.svg?branch=master)](https://travis-ci.org/kevinpapst/kimai2)
[![Code Quality](https://scrutinizer-ci.com/g/kevinpapst/kimai2/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/kevinpapst/kimai2/?branch=master)
@@ -9,25 +9,31 @@ Kimai v2 - the open source time-tracking application with a mobile-first approac
## Introduction
This is the reloaded version of the open source timetracker [Kimai](http://www.kimai.org).
This is the reloaded version of the open source timetracker Kimai.
Right now its in an early development phase, its usable but some advanced features from Kimai v1 are missing by now.
Kimai is based on a lot of great frameworks. Special thanks to:
- [Symfony v4](https://github.com/symfony/symfony)
- [Doctrine](https://github.com/doctrine/)
- [AdminThemeBundle](https://github.com/avanzu/AdminThemeBundle/) (based on [AdminLTE](https://github.com/almasaeed2010/AdminLTE/))
Kimai v2 has nothing in common with its predecessor [Kimai v1](http://www.kimai.org) besides the basic ideas of time-tracking and the current development team.
It is based on a lot of great frameworks. Special thanks to [Symfony v4](https://github.com/symfony/symfony), [Doctrine](https://github.com/doctrine/),
[AdminThemeBundle](https://github.com/avanzu/AdminThemeBundle/) (based on [AdminLTE](https://github.com/almasaeed2010/AdminLTE/)).
## Requirements
### Requirements
- PHP 7.1 or higher
- PHP 7.1.3 or higher
- One PHP extension of PDO-SQLite or PDO-MySQL enabled (it might work with PostgreSQL and Oracle as well, but that wasn't tested and is not officially supported)
- the [usual Symfony application requirements](http://symfony.com/doc/current/reference/requirements.html)
- Kimai needs to be installed in the root directory of a domain or you need to [recompile the frontend assets](var/docs/developers.md)
## Documentation & Roadmap
Looking for more information about using Kimai? Check out our more detailed [documentation](var/docs/).
You can see our development roadmap for the future in the [Milestones](milestones/) sections,
current work is organized in the [Project](projects/) planning boards.
Our roadmap is open for changes and input from the community, please [sent us](issues/) your ideas and questions.
## Installation
First, install Git and [Composer](https://getcomposer.org/doc/00-intro.md)
if you haven't already. Then clone this repo and execute this command in the cloned directory:
First, install Git and [Composer](https://getcomposer.org/doc/00-intro.md) if you haven't already. Then clone this repo:
```bash
git clone https://github.com/kevinpapst/kimai2.git

28
var/docs/developers.md
View File

@@ -66,6 +66,34 @@ You can run the code sniffer with a built-in command like that:
bin/console kimai:phpcs
```
You can also automatically fix the violations by running:
```bash
bin/console kimai:phpcs --fix
```
Be aware that this command will modify all files with violations in the directories `src/` and `tests/`, so its a good idea to commit first.
Our code-styles are configured in [.php_cs.dist](../../.php_cs.dist).
## Translations
We try to keep the number of language files small, in order to make it easier to identify the location of application messages and to unify the codebase.
- If you add a new key, you have to add it in every language file
- Its very likely that you want to edit the file `messages` as it holds 90% of our application translations
The files in `translations/` as a quick overview:
- `AvanzuAdminTheme` is only meant for translating strings from the original theme
- `exceptions` only holds translations of error pages and exception handlers
- `flashmessages` hold all success and error messages, that will be shown as results from action calls after page reload
- `messages` holds most of the visible application translations (like all the static UI elements and form translations)
- `pagerfanta` includes the translations for the pagination component
- `sidebar` holds all the translations of the right sidebar
- `validators` only hold translations related to violations/validation of submitted form data (or API calls)
## Extending the navigation bar
If you want to add your own entries in the navigation bar, you can subscribe to these events: