Commit c6ca2732 authored by Petr's avatar Petr

INIT

parents
# DEV Guide - Client modifications
1. [Development types](./README.md#code-checking-&-requirements)
1. **Client modifications**
2. [Separate existing plugin](./2_SEPARATE_EXISTING_PLUGIN.md)
3. [Separate new plugin](./3_SEPARATE_NEW_PLUGIN.md)
4. [Core implementations](./4_CORE_IMPLEMENTATIONS.md)
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. [Common errors](./COMMON_ERRORS.md)
5. [Repositories](./REPOSITORIES.md)
6. [Testing](./TESTS.md)
Úpravy určené konkrétnímu klientovi dle jeho požadavku. Většinou se jedná o jednorázovou a menší úpravu. Vývoj probíha pouze ve složce vygenerované generátorem (`plugins/easyproject/easy_plugins/modification_*`). Úpravy by měli co nejvíce využívát vlastní controllery/view a volání hooku.
Je důležité, aby veškerý vývoj probíhal pouze ve uvedené složce, protože při aktualizace je vše ostatní smazáne a nahrazene aktuálním kódem.
Patche do jádra jsou povolené jen ve výjmečnýh případech po předchozím schválením. Jsou na **plnou odpovědnost autora**.
Funkčnost kontroluje především klient. U těchto modifikacíh většinou nejsou žádné zásahy do jádra a tudiž probíhají minimální kontroly.
Plugin lze vygenerovat pomoci:
rails generate redmine_extensions:plugin CLIENT_NAME --customer
Nápovědu lze získat:
rails generate redmine_extensions:plugin --help
# DEV Guide - Separate existing plugins
1. [Development types](./README.md#code-checking-&-requirements)
1. [Client modifications](./1_CLIENT_MODIFICATIONS.md)
2. **Separate existing plugin**
3. [Separate new plugin](./3_SEPARATE_NEW_PLUGIN.md)
4. [Core implementations](./4_CORE_IMPLEMENTATIONS.md)
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. [Common errors](./COMMON_ERRORS.md)
5. [Repositories](./REPOSITORIES.md)
6. [Testing](./TESTS.md)
Vývoj/úprava existujicího pluginu pro Redmine, který bude distribuován v rámci Easy Projectu.
Plugin je určený více klientům a tudíž musí být otestován. Buď na úrovni kódu (RSpec, Minitest) nebo definováním scénařů a ručním otestováním.
V těchto pluginech je povoleno využívát pouze vlastní controllery/view. Úpravy jádra jsou povolené **pouze po předchozí domluvě**. V takovémto případě se kontrola patche mění na úroveň [core implementations](#4-core-implementations).
MR může být v opačném případě vráce k přepisu.
Příklad: Easy DMSF
Plugin lze vygenerovat pomoci:
rails generate redmine_extensions:plugin PLUGIN_NAME
Nápovědu lze získat:
rails generate redmine_extensions:plugin --help
Na této úrovní vývoje je nutné psát alespoň základní testy pro "touchnutí" rout a otestování úspěšného stavu. Postup pro testování a jeho nastavení lze najít [na této stránce](./TESTS.md)
# DEV Guide - Separate new plugin
1. [Development types](./README.md#code-checking-&-requirements)
1. [Client modifications](./1_CLIENT_MODIFICATIONS.md)
2. [Separate existing plugin](./2_SEPARATE_EXISTING_PLUGIN.md)
3. **Separate new plugin**
4. [Core implementations](./4_CORE_IMPLEMENTATIONS.md)
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. [Common errors](./COMMON_ERRORS.md)
5. [Repositories](./REPOSITORIES.md)
6. [Testing](./TESTS.md)
Vývoj zcela nového pluginu pro Easy Project. Oproti předcházejíci úrovní je rozdíl, že plugin se vyvíji od začátku a v takovém případě jsou kladené přísnější požadavky.
Na této úrovni je už daná struktůra pluginu, která se generuje pomocí:
rails generate redmine_extensions:plugin PLUGIN_NAME
Nápovědu lze získat:
rails generate redmine_extensions:plugin --help
# DEV Guide - Core implementations
1. [Development types](./README.md#code-checking-&-requirements)
1. [Client modifications](./1_CLIENT_MODIFICATIONS.md)
2. [Separate existing plugin](./2_SEPARATE_EXISTING_PLUGIN.md)
3. [Separate new plugin](./3_SEPARATE_NEW_PLUGIN.md)
4. **Core implementations**
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. [Common errors](./COMMON_ERRORS.md)
5. [Repositories](./REPOSITORIES.md)
6. [Testing](./TESTS.md)
Implementace a úpravy přímo interních pluginu Easy Project. Tedy je brán na kvalitu a předem stanové postupy největší důráz.
Nedodržení pravidel vede k vrácení kódu.
Tato úroveň také vyžaduje dodržování pravidel ohledně stylu kódu popsané v [sekci code style](./CODE_STYLE.md).
## Code review
Kontroly probíhají od nejdůležitějších po ty nejméně. Důležitost označuje samotná cílová větev nebo label important. Naopak `WIP` jsou brány jako poslední.
#### 1. Kontrola náležitostí
Při nedodržení podmínek z předcházející sekce může mít za následek vrácení MR k doplnění bez jakéhokoliv codereview.
Pokud MR obsahuje konflikt nebo špatnou cílovou větev je automaticky vrácen.
#### 2. O čem to je
Odpoǚedná osoba se musí první informovat o důvodu MR buď z popisu nebo z konkrétního úkolu. Nejesnosti automaticky vedou k vrácení MR.
#### 3. Kontrola kódu
1. CI prošlo?
- Důvod pokud neprošli. Nahodilé spadnutí 1 testu není problém.
- Problémy jsou často s feature test na poltregeiste.
2. Lokální test.
- Větší úpravy se kontrolují na živo. Nejlépe na připraveném deployi nebo lokálbě.
- Toto testování je pouze orientační a neslouží k otestování funkcionality. Za tu zodpovídá autor a QA tester.
3. Kontrola kódu.
- Pro tuto problematiku je věnována zvláštní soubor [code style](./CODE_STYLE.md).
4. Hodnocení.
- Každému MR je přiděleno :+1: nebo :-1:.
- Podle hodnocení můžou nastat několik možností
1. Úprava je začleněna
2. Nebo předáná na kontrolu další osobě
3. Nebo vrácena zpět k dodělání
# DEV Guide - Code style
1. [Development types](./README.md#code-checking-&-requirements)
1. [Client modifications](./1_CLIENT_MODIFICATIONS.md)
2. [Separate existing plugin](./2_SEPARATE_EXISTING_PLUGIN.md)
3. [Separate new plugin](./3_SEPARATE_NEW_PLUGIN.md)
4. [Core implementations](./4_CORE_IMPLEMENTATIONS.md)
2. [Development](#development)
3. **Code style**
4. [Common errors](./COMMON_ERRORS.md)
5. [Repositories](./REPOSITORIES.md)
6. [Testing](./TESTS.md)
Tato sekce je určena především pro [interní vývoj jádra](./4_CORE_IMPLEMENTATIONS.md). Pro klientské modifikace nebo samostatný plugin je toto pouze doporučení.
## Editor setup
**2 spaces for indention**
Use 2 spaces for indenting your code and swear an oath to never mix tabs and spaces - a special kind of hell is awaiting you otherwise.
**Unix line-endings**
Use UNIX-style newlines (\n), and a newline character as the last character of a file. Windows-style newlines (\r\n) are forbidden inside any repository.
**UTF-8 source coding only**
**No whitespace**
Just like you brush your teeth after every meal, you clean up any trailing whitespace in your JS files before committing. Otherwise the rotten smell of careless neglect will eventually drive away contributors and/or co-workers.
## Generals
**Do not change Redmine**
Do not change any Redmine files directly. We are plugin for Redmine not a fork.
**Try to use existing code**
Before adding something, inspire yourself with existing codebase. Try to find applicable existing solution, copy and modify it, but of course, remember to use your brain when pasting.
**Do not afraid to explore source code**
Whet you do something, look around for inspiration. Explore models, controllers or views and do it similarly - syntax, code style. If you using any method, you must know what exactly this method do - it mean that you will see whats this method contains.
**Comments**
Comments are required on complex code. Otherwise you should write _self-labeling_ code. It mean that methods name represent what exactly do.
```ruby
# BAD
def convert_date(project, issue, user, date, **options)
...
end
# GOOD
def render_user_name(user)
user.name
end
```
**Quotes**
On Ruby single quotes preffered.
## Desing
##### Klíče překladu
Wording by měl odpovídat překladu a záreň by měl být co nejsrozumitelnější pro prográmátory. Pro klíče se používají prefixy:
- `button_`
- `error_`
- `field_`
- `label_`
- `text_`
- `title_`
##### Inline podmínky
```ruby
# Špatně
check_box_tag :is_default, @model && @model.is_defaut == 'yes' ? '1' : '0', id: 'is_default'
# Dobře
check_box_tag :is_default, (@model && @model.is_defaut == 'yes' ? '1' : '0'), id: 'is_default'
```
##### Odpovídající argumenty
```ruby
# Špatně
def my_method(data, key, value, date, type, other, options={})
# Dobře
def my_method(user, issue, **options)
def my_method(user, issue, html_options: '', html_id: '', date: nil)
```
##### Iterace a pojmenování
```ruby
# Špatně
issues.map{|x| x.project.versions.map{|y| y.css_classes}}.flatten
# Dobře
issues.flat_map { |issue|
issue.project.versions.map { |version|
version.css_classes
}
}
```
##### Case není odsazen
```ruby
# Špatně
case type
when 'issue'
when 'project'
else
end
# Dobře
case type
when 'issue'
when 'project'
else
end
```
##### In HTML
* for `class` attribute use use BEM convention - Block__Element_Modifier / multi-word-block-name__multi-word-element-name_modifier-name_modifier-value for complete reference go to https://en.bem.info/methodology/quick-start/
```html
<div class="easy-query__heading-title_state_selected">...
```
* for `id` attribute use `_` as separator
```html
<div id="easy_entity_import_dialog">...
```
* respect HTML valid syntax
* use our CSS guideline instead own styles
##### Name routing
Named routes are prefered instead hash
```ruby
# BAD
url_for({controller: 'users', action: 'index'})
# GOOD
users_path
```
# DEV Guide - Common errors
1. [Development types](./README.md#code-checking-&-requirements)
1. [Client modifications](./1_CLIENT_MODIFICATIONS.md)
2. [Separate existing plugin](./2_SEPARATE_EXISTING_PLUGIN.md)
3. [Separate new plugin](./3_SEPARATE_NEW_PLUGIN.md)
4. [Core implementations](./4_CORE_IMPLEMENTATIONS.md)
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. **Common errors**
5. [Repositories](./REPOSITORIES.md)
6. [Testing](./TESTS.md)
##### Rails find
- Volání `.find` vyhazuje vyjímky, které je nutné ošetřit. Následujíci kód má vždy potencionál vždy vyhodit chybu 500.
```ruby
Issue.find(params[:id])
```
- Alternativou je použití `.find_by` nebo zachycení vyjímek. V prvním případě je nutné ošetřit nil.
```ruby
begin
Issue.find(params[:id])
rescue ActiveRecord::RecordNotFound
render_404
rescue
@issue = Issue.find_by(id: params[:id])
@issue.project if @issue
```
##### Volání na nil
Je nejčastější problém. Vždy musíte počítat s možností, že proměná je nil.
```ruby
# On Hash
hash[:key1]
hash[:key1][:key2]
# On Array
[].flatten!.map(&:to_i)
# On model
@issue.assigned_to.name
```
##### Reloading v after_save
Ve všech callbacich by se neměla používat metoda `.reload`, protože vyresetuje atributy z [Active Model Dirty](http://api.rubyonrails.org/classes/ActiveModel/Dirty.html).
# DEV Guide
1. [Development types](#development-types)
1. [Client modifications](#1-client-modifications)
2. [Separate existing plugin](#2-separate-existing-plugin)
3. [Separate new plugin](#3-separate-new-plugin)
4. [Core implementations](#4-core-implementations)
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. [Common errors](./COMMON_ERRORS.md)
5. [Repositories](./REPOSITORIES.md)
6. [Testing](./TESTS.md)
## Definitions of terms
- **Easy Project plugins / Jádro:** Jsou všechny pluginy, které jsou vyvýjené interně Easy Software. Jsou tedy jádrem Easy Projectu.
- **Patch:** Úprava, která přímo ovlivňuje chování existující věci. Příklad je použití `alias_method_chain`, `.include`, `.preload`, definování callbacku jako `after_save` / `before_action` nebo použití monkey patchinkg.
- **Úprava jádra:** Patchování interních pluginu Easy Projectu nebo Redmine.
## Development types
Vývoj Easy Projektu je rozdělen na 4 úrovně s různým stupněm kontroly.
#### 1. Client modifications
Úpravy určené konkrétnímu klientovi dle jeho požadavku. Většinou se jedná o jednorázovou a menší úpravu. Vývoj probíha pouze ve složce vygenerované generátorem (`plugins/easyproject/easy_plugins/modification_*`). Úpravy by měli co nejvíce využívát vlastní controllery/view a volání hooku.
Je důležité, aby veškerý vývoj probíhal pouze ve uvedené složce, protože při aktualizace je vše ostatní smazáne a nahrazene aktuálním kódem.
Patche do jádra jsou povolené jen ve výjmečnýh případech po předchozím schválením. Jsou na **plnou odpovědnost autora**.
Funkčnost kontroluje především klient. U těchto modifikacíh většinou nejsou žádné zásahy do jádra a tudiž probíhají minimální kontroly.
[... pokračování](./1_CLIENT_MODIFICATIONS.md)
#### 2. Separate existing plugin
Vývoj/úprava existujicího pluginu pro Redmine, který bude distribuován v rámci Easy Projectu.
Plugin je určený více klientům a tudíž musí být otestován. Buď na úrovni kódu (RSpec, Minitest) nebo definováním scénařů a ručním otestováním.
V těchto pluginech je povoleno využívát pouze vlastní controllery/view. Úpravy jádra jsou povolené **pouze po předchozí domluvě**. V takovémto případě se kontrola patche mění na úroveň [core implementations](#4-core-implementations).
MR může být v opačném případě vráce k přepisu.
Příklad: Easy DMSF
[... pokračování](./2_SEPARATE_EXISTING_PLUGIN.md)
#### 3. Separate new plugin
Vývoj zcela nového pluginu pro Easy Project. Oproti předcházejíci úrovní je rozdíl, že se plugin vyvíji od začátku a v takovém případě jsou kladené přísnější požadavky.
[... pokračování](./3_SEPARATE_NEW_PLUGIN.md)
#### 4. Core implementations
Implementace a úpravy přímo interních pluginu Easy Project. Tedy je brán na kvalitu a předem stanové postupy největší důráz.
Nedodržení pravidel vede k vrácení kódu.
Tato úroveň také vyžaduje dodržování pravidel ohledně stylu kódu popsané v [sekci code style](./CODE_STYLE.md).
[... pokračování](./4_CORE_IMPLEMENTATIONS.md)
## Development
### Before the development
1. Vytvoření účtu na [git.easy.cz](https://git.easy.cz)
2. Přístup do repozitáře (či jeho vytvoření)
3. Seznámení s pravidly s vývoje
### Branches and commits
Všechny důležité větve (pro vydávání balíku nebo pro testování) jsou označené jako **protected** a je zakázano do nich posílat změny přímo. Z tohoto důvodu je nutné nějprve vytvořit větev, která bude obsahovat všechny změny.
Vždy vycházejte z nějnižší možné vývojové verze, aby bylo možné změny začlenit na více míst.
$ git checkout stable
Větve mají definovaný tvar `ID_ÚKOLU-kratky-popis`.
$ git checkout -b 1234-add_author_to_project
Změny se přidávají postupně ve tvaru `refs #ID_ÚKOLU kratky popis`.
$ git commit -m "refs #1234 add migration for author_id"
$ git commit -m "refs #1234 add select to projects form"
Vyhněte se krátkým a neurčitým pojmenovávání jako _fix_, _patch_ nebo _edit_. Správně pojmenovávání je důležité z důvodu prohlížení historie. Komit ve tvaru "refs #1234 fix author migration" řekne mnohem více než "fix".
V případě kdy úkol neexistuje je třeba psát podrobnější popisy.
### Merge requests
Pro začlenění úprav se vytváří merge (pull) request, kde proběhne diskuze na kódem a funkcionalitou. Stejně jako větve má MR své zásady.
#### 1. Název
By měl být krátký, stručný a zárověň popisovat co se děje. Pokud je úprava spojena s úkolem tak zároveň i referenci na něj `refs #ID_UKOLU`.
Správně:
- 500 na úpravě úkolu (refs #123456)
- Nová verze ganttu 2.0
Špatně:
- fix
- patch
- refs #123456
Mějte na paměti, že přiřazený úživatel vidí ve svém seznamu jen název MR. "Important project fix" bude jistě vyřízen dříve než jen "patch".
Pokud MR není dokončeny a němel by být začleněn můžete do názu přidat **WIP:** (wotk in progress).
#### 2. Popis
Detailnější popis problému a změn. Pokud na úpravu existuje úkol musí popis vždy obsahovat plný odkaz ně nej. V opačném případě musí obsahovat detailnější popis.
#### 3. Větve
Cílová větev vždy závísí na definovanách pravidel daného repozitáře. Více informací v sekci [Repozitíře](./REPOSITORIES.md)
#### 4. Přiřazení
Při vytvoření je vždy autor.
#### 5. Po vytvoření
Po vytvoření je nutné **VŽDY** MR zkontrolovat. Změny musejí sedět s úpravou a MR nemůže obsahovat konflikt.
V repozitář s nastaveným CI je nunté nejprve počkat na doběhnutí testu.
V případech, kdy MR obsahuje konflikty, neprošli testy nebo podpobné situace dojte ke vrácení MR a zbytečnému zdržování.
Pokud je vše v pořádku může se MR přeřadid na odpovědnou osobu nebo správce repozitáře. Pokud si nejste jistí lze u Easy Projectu zvolit @lukas nebo @ondra. U ostatních typů lze zvolit i @jaroslav.bohmer .
### Společné zásady pro všechny úrovně
##### Plugins intializing
Pluginy v Easy Projectu načítájí pluginy jiným způsobem než je to ve vanila Redmine. Ten pro nahrání plugin využívá pouze soubor `init.rb`. V Easy Projectu je inicialize rozdělena na 2.
- `init.rb` obsahuje pouze registraci pluginu
- `after_init.rb` obsahuje vše ostatní
V případě vývoje pluginu, který má běžet jak Redmine tak pro Easy Project může zajistit kompatibilitu pomoci následujícího kódu, který vložíte na konec souboru `init.rb`
```ruby
if Redmine::Plugin.registered_plugins[:easy_extensions].nil?
require_relative 'after_init'
end
```
##### Prefixes
Aby se předešlo zbytečným konfliktům je dobré veřejné věci oprefixovat. Například název pluginu bude `AbcPlugin` místo `Plugin`.
Veřejné věci jsou ty které se dají přímo volat ze všech míst programu.
```ruby
class AbcModel
has_many :others # vnitřní metoda, která nebude v konfliktu s ostatními věcmi
has_many :abc_others # a tudíž jí není třeba prefixovat
end
AbcModel # => lze volat odkudkoliv
```
##### Languages
Předchozí sekce se vztahuje i na definování klíčů pro lang soubory. Například klíč `label_sum: Abc sum` se může dostat do konfliktu se stávajícím klíčem a proto je nutné udělat prefix na `label_abc_sum`.
Zároveň je **zakázano** měnit/přepisovat existující klíče z Redmine nebo Easy Projectu.
Všechny texty **musí využívát** systém I18n a minimálně **musí být** přeložené do angličtiny.
##### Syntax checking
Syntax error není tolerovaný na žádné úrovní. V takovém to případě dojde k okamžitému vracácení MR jelikož kód nemohl byt v žádném případě otestovaný.
Tyto chyby lze snad odhalit pomocí `ruby -wc CESTA_K_SOUBORU`. Pro kontrolu nad všemi soubory lze použít tento příklad:
```
find . -name "*.rb" -type f -exec ruby -wc {} \; | grep -v OK
```
# DEV Guide - Respositories
1. [Development types](./README.md#code-checking-&-requirements)
1. [Client modifications](./1_CLIENT_MODIFICATIONS.md)
2. [Separate existing plugin](./2_SEPARATE_EXISTING_PLUGIN.md)
3. [Separate new plugin](./3_SEPARATE_NEW_PLUGIN.md)
4. [Core implementations](./4_CORE_IMPLEMENTATIONS.md)
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. [Common errors](./COMMON_ERRORS.md)
5. **Repositories**
6. [Testing](./TESTS.md)
## easyproject/devel
```
+--------+
| devel |
+---+----+
|__________________
|
+--------+ +--------v----------+
| early |<---| early-on-testing |
+---+----+ +-------------------+
|__________________
|
+--------+ +--------v----------+
| stable |<---| stable-on-testing |
+--------+ +-------------------+
```
- `devel`
- Hlavní vývojová větev pro nové věci
- (nejméně stabilní větev)
- `early`
- Vydaná větev předběžného přístupu
- `early-on-testing `
- Pro testování early branche a pro opravy bugu
- `stable`
- Poslední vydána stabilní větev
- `stable-on-testing`
- Opravy bugu, které se najdou při testování nové verze
- Všechny MR měřující do této branch podléhájí nejpřísnějšímu hodnocení
- Nutná maximální opatrnost
## Gantt, Resource management, WBS
```
+-------+ +-------------------+ +--------+
| devel |--->| release_candidate |--->| master |
+---+---+ +-------------------+ +--------+
```
- `devel`
- Pro nové věci
- `release_candidate`
- Větev nad kterou se testuje vydání nového balíku
- Poue opravy bugu
- `master`
- Stabilní vydaná verze
- Pouze kritické opravy které nepočkají na testování
# DEV Guide - Tests
1. [Development types](./README.md#code-checking-&-requirements)
1. [Client modifications](./1_CLIENT_MODIFICATIONS.md)
2. [Separate existing plugin](./2_SEPARATE_EXISTING_PLUGIN.md)
3. [Separate new plugin](./3_SEPARATE_NEW_PLUGIN.md)
4. [Core implementations](./4_CORE_IMPLEMENTATIONS.md)
2. [Development](#development)
3. [Code style](./CODE_STYLE.md)
4. [Common errors](./COMMON_ERRORS.md)
5. [Repositories](./REPOSITORIES.md)
6. **Testing**
Bude doplněno.
# Easy Doc
1. [Install](./INSTALL)
2. [Upgrading](./UPGRADING)
3. [Licence](./LICENSE)
4. [UI Guide](./UI/README.md)
5. [DEV Guide](./DEV/README.md)
Easy Software Ltd.
https://www.easysoftware.com
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment