# Zbiór dobrych praktyk
Dokumentacja sprządzona dnia 19 lipiec 2018
Modyfikacja: 25 grudzień 2020
Autor: Michał Bahn
Wersja 1.4

Do poprawy: literówki, tłumaczenia
Do uzupełnienia:
[ ] testowanie projektów,

---
Niniejszy dokumnet zawiera zbiór dobrych praktyk z przestrzeni utrzymania porządku w kodzie oraz zasad współpracy grupowej.

Pliki konfiguracyjne w repozytoriach projektowych [ DRAFT! ]
---
Take an example where you have a config file named "`config.ini`". In the working directory of your git repo, you would do the following:

Create a version of the config file called "`config-sample.ini`". This is the file you'll do all your work on.

Create a **symbolic link** between "`config.ini`" and "`config-sample.ini`".

ln -s config-sample.ini config.ini

This let's all your code point to "`config.ini`" even though you're really maintaining "`config-sample.ini`". Update your `.gitignore` to prevent the "`config.ini`" from being stored. That is, add a "`config.ini`" line:

echo "config.ini" >> .gitignore

(Optional, but highly recommended) Create a **.gitattributes** file with the line "config.ini export-ignore".

echo "config.ini export-ignore" >> .gitattributes

Do some coding and deploy....

.
.
.

After deploying your code to production, copy the "`config-sample.ini`" file over to "`config.ini`". You'll need to make any adjustments necessary to setup for production. You'll only need to do this the first time you deploy and any time you change the structure of your config file.

**A few benefits of this:**

* The structure of your config file is maintained in the repo.
* Reasonable defaults can be maintained for any config options that are the same between dev and production.
* Your "config-sample.ini" will update whenever you push a new version to production. This makes it a lot easier to spot any changes you need to make in your "config.ini" file.
* You will never overwrite the production version of "config.ini". (The optional step 4 with the .gitattributes file adds an extra guarantee that you'll never export your "config.ini" file even if you accidentally add it to the repo.)

Nomenklatura i struktura katalogów na serwerach
---
**Cleansystem** traktujemy developersko - nasze eksperymenty, staging testowy itd.
**Berryprojekct** traktujemy jako serwer produkcyjny i tu kładziemy wyłącznie projekty w wersji live (produkcyjne), które sami hostujemy dla klientów.

### 1. Nazwa bazowa
- o ile to możliwe, nazwa powinna być krótka lecz jednoznaczna i dotyczyć marki klienta np. wedel, sferia, cocacola, urzadpocztowy
- w nazwach unikamy skrótów które mogą być mylące
- w nazwie marki/firmy nie używamy spacji ani podkreślników
- nazwy tworzymy z małych liter

### 2. Typ realziacji
Tworząc człon z typem realizacji ==po myślniku== wpisujemy typ realizacji:
- **www** - dla stron
- **lp** - dla landingpage-ów
- **sklep** - dla realizacji ecommerce
- **blog** - dla blogów
- **app** - dla applikacji
- **api** - dla applikacji w postaci typu API
- **lib** - niezleżna bibloteka

### 3. Identyfikator realziacji
Jeśli istnieje potrzeba rozróżnienia projektów w ramach jednego klienta i takich samych typów projektów, wprowadzamy ==po podkreślniku== krótki 2-3 literowy symbol lub numerację. Oznaczenia symbolicze są zawsze lepiej widzane niż numeracyjne.

Przykładowo:
- winiary-lp **_star** - sugeruje np LP ze starterami
- winiary-lp **_kon** - sugeruje np LP konkursowy

lub mniej jednoznacza identyfikacja numeracyjna:

- winiary-lp **_1**
- winiary-lp **_2**

### 4. Typ frameworka
Jeśli to możliwe, określamy technologię jako przedostani ostatni parametr ==po myślniku==. Dotyczy to wyłącznie projektów stawianych na frameworkach. Terminy określające technologię powinny być nie dłuższe niż 4 znaki i jednoznacznie definiujace technologię. Gdy projekt jest wykonywany bez użycia frameworku nie wpisujemy żadnego oznaczenia.

- **wp** - wordpres,
- **jom** - joomla,
- **lara** - laravel,
- **symf** - symfony,
- **zend** - zend,
- **prst** - presta,
- **mag** - magento,
- **rct** - react,
- **aglr** - angular

Dla przykładu:

- wedel-blog **-wp** - dla bloga stworzonego w wordpress
- wedel-www **-lara** - dla strony w laravelu
- airbus-app **-rct** - dla apliakcji w react
- airbus-app **-aglr** - dla apliakcji w angularze

### 5. Osoba prowadząca
Jako ostatni parametr, po podwójnym myślniku, określamy głównego wykonawcę (założyciela projektu). Nazwę wyprwadzamy z inicjałów, przykładowo --jk dla Jan Kowalski.

Przykładowo:
- wedel-www-lara-- **jk**
- sony-www-- **jk**

### 6. Podsumowanie

Ostateczny wygląd nazwy przykładowego katalogu

/wedel-sklep_2-mag--jk/

Co oznacza:

klient: **Wedel**
realizacja typu: **ecommerce**
jest to kolejna, druga realizacja sklepowa dla tego samego klienta
framework to **Magento**
właścicielem/prowadzącym projekt jest **Jan Kowalski**

/wedel-www_brand-wp--jk/

Co oznacza:

klient: **Wedel**
realizacja typu: **www**
jest to realizacja o identyfikatrorze **brand**
framework to **WP**
właścicielem/prowadzącym projekt jest **Jan Kowalski**

### 7. Struktura katalogów root
Aby nie zaśmiecać głównego katalogu root-owego serwera proponuję utworzyć tylko kilka głównych katalogów sugerujących typ projektu lub usługi. A zatem:

| Katalog | Opis |
| :------| :-----------|
| private | katalog systemowy |
| tmp | katalog systemowy |
| download | katalog systemowy |
| Ania | indywidualny katalog użytkownia Ania na eksperymenty własne, chwilowe testy. (Nie można tu kłaść projektów klienckich, bo katalogi te będą usuwane wraz z odejściem pracownika) |
| Michal | indywidualny katalog użytkownia Michał ...
| Wojetek | indywidualny katalog użytkownia Wojtek ... |
| **development** | katalog z podkatalogami klientów |
| **produkcja** | katalog z katalogami produkcyjnymi projektów |
| arch | katalog który zawiera projekty do archiwizacji |

Nomenklatura oznaczeń baz danych (DB)
---

### 1. Identyfikator
Identyfikator bazy jest często narzucany z góry przez system hostingu i prezentowany jest jako losowy ciag numerowy. Jelsi istnieje dowolność w nazewnictwie, podajemy pierwszy człon jako `00000001` (7 zer).

### 2. Nazwa bazowa
Jako drugi człon podajemy ==po podkreślniku== (underscore) nazwę projektu (klienta lub konkretnej realzaicji klienckiej). Nazwa powinna być jednoznaczana i możłiwe któtka, do 8 znaków.

### 3. Typ realizacji
Jako trzeci człown ==od podkreślnika== zanzaczmy typ realziacji dla którego założona zostaje baza. Wyrózniamy typy: **sklep**, **app**, **cms**.
Jeśi w projekt jest zaangażowany popularny opensourcowy framework, możemy użyć jego identyfiaktora: **wp**, **jom**, **drup**.

### 4. Identyfikator
Identyfikator podajemy ==po podkreślniku== i dookreśla on status bazy. Może on wskazywać na backup, wersję developerską, itd:
**backup**, **test**, **dev**, **migacja**

### 5. Podsumowanie
Ostateczny przykładowy wygląd kilku nazw baz:

06822244_noosicon_sklep
06822244_noosicon_sklep_backup
06822244_sony_cms
06822244_orbis_www
06822244_orbis_www_dev
06822244_orbis_www_migracja

### 6. Opis
Polem **obowiazkowym** jest opis bazy. Precyzuje czym jest baza powinien składać się wkilku podsawowych informacj jak klient, nazwa projektu, typ realziacji, opis wskazujący na zawartość bazy oraz osobę tworząca i przybliżoną datę powsatnia. Przykładowo:

Schaffashoes Noosicon | sklep | aktualna baza sklepu [Michał 08.2018]

Zabezpieczenie katalogu
---
Każdy katalog projektowy zarówno na serwerze produkcyjnym jak i stagingowym powinien zostać zabezpieczony i prawidłowo opisany. W zakres zapezpieczenia katalogu wchodzą odpowiednio skonfigurowane:
`.htaccess` - zabezpieczenie dostępów
`info.php` - przezentacja bieżacej konfiguracji
`index.htm` - plik blokujący listowanie katalogu
`REDME.md` - informacje o projekcie

### 1. Plik .htaccess

################################################
### Wersja PHP
################################################
:Location /*.php
Use php73
:Location


################################################
### PRIORYTET PLIKÓW STARTOWYCH 
################################################
DirectoryIndex index.php index.html index.htm default.htm info.php


################################################
### ZABEZPIECZENIE LISTOWANIA KATALOGU
################################################
# Dla starych hostingow home.pl 
Options -DirList

# Dla nowych hostingow home.pl
Options -Indexes

# Disable directory browsing
Options All -Indexes

# Dla hostingow home.pl dyrektywa nie jest obslugiwana
IndexIgnore *.md


################################################
### ZABEZPIECZENIE KLUCZOWYCH PLIKÓW
################################################
# Zabezpieczenie .htaccess
<Files .htaccess>
  Order Allow,Deny
  Deny from all
</Files>

# Zabezpieczenie odmian .htaccess
<Files ~ "^.*\.([Hh][Tt][Aa])">
  order allow,deny
  deny from all
  satisfy all
</Files>

# Zabezpieczenie pobrania README.md
<Files README.md>
  Order Allow,Deny
  Deny from all
</Files>

# Zabezpieczenie przed zczytaniem repo .git
<DirectoryMatch "^/.*/\.git/">
    Require all denied
</DirectoryMatch>

### 2. Plik info.php
Na serwerze produkcyjnym plik z informacją o bieżącej konfiguracji, **powinien być dezaktywowany** (wykomentowana linia funkcji) po finalnym uruchomieniu produkcyjnym.
plik nie nosi brdzo szkodliwych informacji, jednak nie powinno się ujawniać potencjalnych luk np związanych z użyciem przestarzałych biblotek, czy ścieżek do katalogów tymczasowych itp...

<?php 
  phpinfo();
?>

### 3. Plik README
Strktura pliku omówiona w osobnym rodziele.

### 4. Plik index.htm
Plik osadzany w katalogu głównym dodatkowo zabezpiecza wyświetlanie struktury katalogów foldera projektowego. Odpowiednio spreparowany `.htaccess` umożliwia współistnienie pliku z plikami `index.html` czy `index.php` i adekwatnie uruchamianie ich z wyższym priorytetem. Plik ten powinien zawierać jedynie nazwę projeku (lub zaślepkę w formie prostego LP-ka), która będzie wyświetlana zanim na serwerze nie pojawi się oprogramowanie docelowe.

Pliki README.md
---
### 1. Uwagi ogólne
Pliki **README.md** są obowiązkową częścią projektów, opisują warunki powstania projektu, podstawowe problemy projektu, warunki na które developer powinien zwrócić uwagę. Nie powinno się zaniedbywać takich informacji głownie na fakt czasowej ulotności szczegłów projektu,które w pszyszłości mogą być bardzo pomocne i zaoszczędzić sporo czasu i kłopotów.

Przykładowy plik:

# Informacje o projekcie
Projekt: **Strona Architekta Kowalski** - (czerwiec 2019)
Autor: **Janek Kowalski, Anna Kowalska**
Technologie: [ HTML, JS, CSS, WP ]

TO-DO:
- [ ] **Ogólne**
    - [x] Dodac plik dokumentacji README
- [ ] **Backend**
    - [ ] Poprawić funkcję mailongową
    - [ ] Zmienić hasła dostępowe dla użytkownika Krzysiek 
- [ ] **Frontend**
    - [ ] Poprawić w pliku CSS stylowanie kontaktu

Opis:
---
Strona oparta na systemie WP, prezentująca ofertę biura architektonicznego.    


Struktura:
---
'```
root
├──[_deployment]        -katalog techniczny deploymentu
│   └──[backup]         -katalog techniczny backupu poprzedzajacego aktualziację
│   └──[backup-staging] -katalog techniczny backupu poprzedzajacego aktualziację
│   └──[tmp]            -katalog techniczny tymczasowego repo
│   └──[tmp-staging]    -katalog techniczny tymczasowego repo
└──[assets]             -katalog aplikacji
│   └──[default]        -katalog fontów
│   └──[default]        -katalog obrazów
│   └──[default]        -katalog skryptów JS
│   └──[default]        -katalog styli CSS
│   └──app.js           -plik importowy
│   └──html5shiv.js     -zapewnia kompatybilność dla < IE9
└──[templates]          -katalog plików widoku
│   └──[default]        -katalog z plikami widoków strony
│   └──[mails]          -katalog z plikami szablonów powiadomień
│   └──app.js           -głowny plik szablonu 
└──.gitignore           -wykluczenia GIT
└──.config.yml          -konfiguracja startera 
└──README.md            -dokumentacja projektu

'```

Konfiguracja:
---
W pliku config.yml zadeklaruj:
 * wartosć  porojektu 
 * email na który mają zostać wysłane powiadomienia 
 

Uwagi:
---
Brak


Zauważone problemy:
---
Chwilowy brak stylów podczas czyszczenia cache aplikacji i rekompilacji widoku.  


Deployment:
---
W  projekcie zastosowano automatyczny deployment. Wystarczy 'push' z odpowiednio dodanym  tagiem, a repozytorium Gitlab powiadomi serwer produkcyjny który zaciągnie zmiany na serwer  i wywoła czyszczenia cache oraz rekomplikację wszystkich składników wchodzących w skład widoku.    


#### 1. Sprawdź zminay w repozytorium klienta
Sprawdź nowe zminay zacommitowane w repozytorium klienta:
`https://gitlab.com/berryproject/costam-costam--orig.git`

#### 2. Nanieś zmiany w projekcie startera
Nanieś zmiany w plikach szablonów, pamiętając by w pliku `assets/app/js` zamieścić wszystkie  
wchodzące w skład widoku elementy!    

#### 3. Wypchnij zmiany do repozytorium
`ID_Commita_klienta` , `Opis commtu klienta` oraz `Developer Klienta` pobierze z 
ostaniego commita repozytorium klienta.  

'```
git add * 
git commit -m '[ID_Commita_klienta] Opis commtu klienta - Developer Klienta'    
git tag -a  v1.4.[NR_Kolejny] [ID_Commita]
git push origin master
'```

### 2. Uwagi edycyjne

Dokumentacja w pliku może być skrócona. Jeśli to standardowa apliakcja jak WP, nie ma sensu prezentować całej struktury projektu, nie ma też wyznaczonych procesów deploymentu, ale już uwagi mogą być bardzo pomocne.
W przypadku struktur dla WP tworzymy widok ścieżki do pliku konfiguracyjnego, oraz do katalogu użytego theme ewntualnie child-theme. Ideą sodtworzenia strktury jest pozwolenie na szybkie rozeznanie się gdzie są kluczowe pliki projektu (np. ktoś może umieścić pliki źródłowe kodu nieskomplilowanego poza domyślną strukturą theme).

### 3. Minimalny plik **README.md**

:::info
**UWAGA:** W tworzonym pliku usuń pierwszy apostrof z ciagu: '```
:::

# Informacje o projekcie
Projekt: ** NAZWA ** - ( DATA )
Autor: ** AUTOR **
Technologie: [ TECHNOLOGIE,TECHNOLOGIE ]

TO-DO:
- [ ] ** ZAKRES **
    - [x] WYKONANY   
    - [ ] DO ZROBIENIA 

Opis:
---
MÓJ OPIS

Struktura:
---
'``` 
root
└──[templates]          -katalog plików widoku
│   └──[moj_szablon]    -katalog z plikami widoków strony
└──.htaccess            -konfiguracja dostepowa
└──index.htm            -zabezpieczenie katalogu
└──info.php             -plik informacyjny konfuguracji srodowiska
└──README.md            -dokumentacja projektu
'``` 

Konfiguracja:
---
INFORMACJE O KONFIGURACJI

Uwagi:
---
UWAGI DO PROJEKTU
 
Zauważone problemy:
---
UWAGI O PROBELMACH JEŚLI ZAUWAŻONO LUB JEŚLI WYSTĄPIŁY W PRZESZŁOŚCI

Deployment:
---
OPIS DEPLOYMENTU JEŚLI POTRZEBNY

Praca z GIT
---
### 1. Skonfiguruj swojego GIT
W celu rozpoznawnia zmian nanoszonych przez poszczegółnych developerów GIT używa identyfikatorów. Każdy deweloper jest zobowiązany skonfigurować swoje środowisko. Użyj poniższych instrukcji by globalnie (`--global`) w obszarze swojego hosta nadać swoim zmianom swój identyfikator.

git config --global user.name "Jan Kowalski"
git config --global user.email "[e-mail]"

### 2. Dostępy do GITLAB
W celu współrpacy z pozostałymi członkami zespołu musisz mieć dostęp do **GitLab**. Poproś kierownika projektów, o przydzielenie Cię do odpowiedniej grupy projektowej. W zgłoszeniu musisz podać swój email, który jest jednocześnie twoim identyfikatorem.

### 3. Tworzenie repozytorium
Istnieją trzy sposoby tworzenia repozytorium dla trzech różnych stadium projektowych.

#### 1. Istniejący projekt w repozytorium
Procedura tworzenia poprzez klonowanie zawartości repozytorium. Jeśli repozytorium ma status prywatne, będziesz mucieś uzyć loginu i hasła.

git clone https://gitlab.com/berryproject/_boilerplate.git
cd _boilerplate

:::info
**Tips:** Jeśli użyjesz symbolu odstępu i kropki (` .`) na końcu komendy klonowania, repozytorium zostanie wypakowane wprost do katalogu, w którym się aktualnie aktualnie znajdujesz.
:::

git clone https://gitlab.com/berryproject/_boilerplate.git .

#### 2. Tworzenie repozytorium dla istniejacego projektu
Procedura tworzenia nowego repozytorium z istniejacego lokalnie folderu projektowego. Ay móc wypchnąć repozytorium na GitLab, musisz mieć wcześniej utworzone repozytorium. ==Nie tworzysz samodzielnie repo, lecz zgłaszasz== potrzbę istnienia takiego repozytorium kierownikowi projektów. *Proces zakładania nowego repozytorium ogrniczony jest urawnieniami całej grupy projektowej. Zakładając repozytorium samodzilnie, nie przydzielisz uprawnień całej grupie projektowej.*

cd existing_folder
git init
git remote add origin [e-mail]:berryproject/nazwa_projektu.git
git add .
git commit -m "Initial commit"
git push -u origin master

Wypchnięcie zmian do repozytorium powinno zakończyć się komunikatem sukcesu. Jeśli występują błędy, masz problem z zautoryzacją dostępu lub przydzielonymi uprawnieniami. Zgłoś problem kierownikowi projektu.

Tworzenie nowego projektu
---
Pobiermay Wordpress wersję PL

wp core download --locale=pl_PL

Konfigurujemy bazę danwych:

wp core config 
--dbname=nazwa_bazy_danych  
--dbuser=użytkownik_bazy_danych  
--dbpass=hasło_do_bazy_danych  
--dbhost=localhost  
--dbprefix=wp_ 

Nastęþnie konfihurujemy

wp core install 
--url=adres_url.pl
--title="Nazwa stroy" 
--admin_user=admin 
--admin_password='jakieś_hasło'
--admin_email=[e-mail]

Tworzenie nowego projektu z boilerplate repo
---

Rozpoczynając pracę z nowym projektem wararto stosować się do zunifikowanych ustaleń odnośnie struktury projektu, procedur jak i samego środowiska pracy. Konfiguracja środowsika projektu jest często procesem zestandaryzowanym, powtarzalnym dlatego możesz posłużyć się gotowymi schematami - boilerplate.

#### 1. Pobierz boilerplate
W nowym katalogu projektu wykonaj komendę:

git clone https://gitlab.com/berryproject/_boilerplate.git . 

Usuń zawartość lokalnego repozytorium .git dla boilerplate gdyż jego instacnaj wraz z historią nie będzie ci już potrzebna.

#### 2. Zainicjuj nowy projekt
Zainicjuj nowy projekt, podajac adres nowo utworzonego projektu w repozytorium GitLaba.

git init
git remote add origin [e-mail]:berryproject/nazwa_projektu.git 

#### 3. Oczyść projekt
Usuń zbędną zawrtoś boilerlate. Szablony projektu mogą posiadać przykładowe nadmiarowe pliki konfiguracyjne.
Ustal, które z katalogów/plików są istotne dla Twojego projektu, poustawiaj stosowne wpisy w `.gitignore` wykluczające pliki nie osadzane w repozytorium.

Gdy już wszystko będzie zgrubsza gotowe, dodaj zmiany do indeksu i zakomituj dokonane modyfikacje:

git commit -m "Initial commit" 

#### 4. Opisz projekt
Bardzo ważnym jest uzupełnienie pliku README.md znajdujacycm się w głównym katalogu projektu. Jest to informacja dla pozostałych deweloperów, o tym czego dotyczy projekt, jakie użyte są wnim technologie, jakich projekt wymaga konfiguracji oraz co należy uwzględnić w tarakcie jego developowania lub deploymentu.

W pliku tym powiny się znaleźć informacje:
* jakich modyfikacji wymaga projekt w przyszłości
* lokalziacja plików konfiguracyjnych
* bieżących ustawień dla całej aplikacji
* sposobu organizacji środowiska developerskiego,
* sposobu organizacji środowiska testowego/produkcyjnego
* metodyki deploymentu
* sposoby wytyczne wspołpracy z zewnętrznymi zasobami/aplikacjami
* zasygnalizowanie problemów jakie stwarzał projekt i sposobów ich rozwiązań

Po zakońcedniu edycji dodaj do indexu GIT jedynie plik README.md i zakomituj dokonaną modyfikację:

git add README.md
git commit -m "Aktualziacja dokumentacji - README.md" 

**Uwaga:** Pamiętaj by stale aktualizwać zawartość pliku, aby informacje w nim zawarte były ++zawsze++ aktualne.

:::success
Od sposobu i sumienności prowadzenia dokumentacji zależeć będzie komfort pracy całego zespołu. **Nigdy pod presją czasu, nie zaniedbuj obowiazku dokumentacji** - traktuj ją jak nieodłaczny element projektu i zawsze rezerwuj czas na jej poprowadzenie.
:::

#### 5. Skonfiguruj środowisko

Najczęściej boilerplate zwiera jedynie przykłady konfiguracji. Musisz dostosować te ustawienia do wymogów swoich i całego projektu. Zwróć uwagę na pliki w odmianach localdev/dev/prod sugerujacych inne ustawienia dla odrębnych środowisk. W pliku README.md wstępnie opisane są prcedury, które musisz uwzględnić podaczas konfiguracji, skorzytaj z nich by ułatwić sobie pracę.

RWD
---
Maksymalna list rodzielczości dla jakeiej robimy optymalziacje

@media (max-width: 1679.98px /*native 1680*/) { }
@media (max-width: 1439.98px /*native 1440*/) { }
@media (max-width: 1365.98px /*native 1366*/) { }
@media (max-width: 1279.98px /*native 1280*/) { }
@media (max-width: 1199.98px /*native 1200*/) { }
@media (max-width: 1079.98px /*native 1080*/) { }
@media (max-width: 1023.98px /*native 1024*/) { }
@media (max-width: 961.98px /*native 962*/) { }
@media (max-width: 767.98px /*native 768*/) { }
@media (max-width: 719.98px /*native 720*/) { }
@media (max-width: 639.98px /*native 640*/) { }
@media (max-width: 479.98px /*native 480*/) { }
@media (max-width: 411.98px /*native 412*/) { }
@media (max-width: 374.98px /*native 375*/) { }
@media (max-width: 359.98px /*native 360*/) { }
@media (max-width: 319.98px /*native 320*/) { }

Podstawowy bootstrap:
grid-breakpoints:
xs: 0, // Extra small screen / phone
sm: 576px, // Small screen / phone
md: 768px, // Medium screen / tablet
lg: 992px, // Large screen / desktop
xl: 1200px // Extra large screen / wide desktop

container-max-widths:
sm: 540px,
md: 720px,
lg: 960px,
xl: 1140px

Testowanie projektów
--

https://sitechecker.pro/
http://nibbler.silktide.com/pl_PL

https://www.powermapper.com/

testy automatyczne dla programistóœ
https://www.cypress.io/

Nomenklatura dla plików graficznych
--

:::success
[definicja] _ [lokalziacja] _ [określnik] _ {nr}.[rozszerzenie]
:::

Przykłady:

bg_sidebar-postac.jpg
foto_galleria-konieta_2.jpg
foto_homepage-onas_czerwone-ferrari_v005.jpg
elm_galleria-strzałka.png

Staramy się utrzymać możliwe krótkie nazwy , BEZ POLSKICH znaków diakrytycznych i znaków specjalnych, wszystkie pisane małymi literami.

### DEFINICJA
**bg_** - background. tło
**icon_** - ikona
**elm_** - element
**thumb_** - miniatura
**foto_** - fotografia

### LOKALIZACJA
**sidebar** - boczne menu
**top** - nagłówek strony
**intro** - sekcja prezentacyjna
**footer** - stopka
**galeria** - galeria lub grupa fotografii
**sekcja** - charakterystyczny wydzielony obszar
**karuzela**- galeria ruchoma

**Uwaga:** w razie potrzeby można stworzyć własną nazwę,, oddającą umiejscowienie grafiki w przestrzeni strony. Lokalizacja może łączyć wyrazy tworząc zwarte konstrukcje typu: homepage-galeria, co oznacza zastosowanie grafiki tylko w galerii na homepage.

### OKREŚLNIK
Informacja ta definiuje co prezentuje wybrany obraz. Tu jest pewna dowolność w nazewnictwie. Stosujemy KRÓTKIE wyrazy, a ściślej najkrótsze jak się da. Jeśli potrzeba, możemy tworzyć frazy dwu-trzy-wyrazowe stosując myślnik jako łącznik, np.: samochod-spotrowy, kobieta-w-kapeluszu, gesty-las, robet-urbanski.
Opis powinien pozwalać zorientować się w liście plików z jakim zasobem mamy do czynienia - nie precyzowanie opisów.W przypadku serii zdjęć o podobnym charakterze należy zastosować prosty określnik i użyć numeratora (o czym niżej).

### NR
Nie jest obligatoryjny. Numerację stosujemy jeśli potrzeba: zachować kolejność, gdy obiekt występuje w kilku wersjach, lub gdy mamy do czynienia z całą serią grafik.
Przykład:

foto_galleria-konieta_1.jpg
foto_galleria-konieta_2.jpg
foto_galleria-konieta_3.jpg

**Wersjonowanie:**
Wersjonowanie, stosujemy gdy mamy do czyniania z kolejnymi modyfikacjami danego obrazu. Numerator poprzedzamy małą literą ‘v’ np: _v001.

W przypadku wersjonowania, zachowujemy następującą regułę zgodności:
`elm_malina.jpg` - oryginalny plik
`elm_malina_v001.jpg` - pierwsza odmiana oryginału a zatem 2 jego wersja
`elm_malina_v002.jpg` - druga odmiana oryginału a zatem 3 jego wersja
`elm_malina_v012.jpg` - dwunasta odmiana oryginału a zatem 13 jego wersja

### ROZSZERZENIA
**.jpg** - stosujemy dla fotografii
**.png** - stosujemy dla niewielkich elementów geometrycznych w których istotne jest uzyskanie transparentnego tła
**.svg** - stosujemy dla elementów wektorowych, dla których przewidziane jest znaczne skalowanie.

### ROZMIARY MINIATUR GRAFICZNYCH
16 x 16 – Standard size for browsers (favicon)
24 x 24 – IE9 pinned site size for user interface
32 x 32 – IE new page tab, Windows 7+ taskbar button, Safari Reading List sidebar
48 x 48 – Windows site
57 x 57 – iPod touch, iPhone up to 3G
60 x 60 – iPhone touch up to iOS7
64 x 64 – Windows site, Safari Reader List sidebar in HiDPI/Retina
70 x 70 – Win 8.1 Metro tile
72 x 72 – iPad touch up to iOS6
76 x 76 – iOS7
96 x 96 – GoogleTV
114 x 114 – iPhone retina touch up to iOS6
120 x 120 – iPhone retina touch iOS7
128 x 128 – Chrome Web Store app, Android
144 x 144 – IE10 Metro tile for pinned site, iPad retina up to iOS6
150 x 150 – Win 8.1 Metro tile
152 x 152 – iPad retina touch iOS7
196 x 196 – Android Chrome
310 x 150 – Win 8.1 wide Metro tile
310 x 310 – Win 8.1 Metro tile

## Instalacja projektu Brain Embassy
1. git clone z repozytorium
2. zip node_modules.zip rozpakować do folderu "node_modules"
3. gulp -v, powinny byc:
*CLI version: 2.3.0
Local version: 3.9.1* ,
jeśli nie ma Local version, albo jest inna wersja doinstalować: npm install gulp@3.9.1
5. w pliku npm-shrinkwrap.json nadpisać całość tym (źródło: https://stackoverflow.com/a/60921145 - błąd: "ReferenceError: primordials is not defined")

{
   "dependencies": {
      "graceful-fs": {
          "version": "4.2.2"
      }
   }
}

5.

npm install

6.

gulp

#### Troubleshooting
Jeśli po podmianie zawartości npm-shrinkwarp.json są problemy z wykonaniem komend to należt spróbować skopiować pliki config (gulpfile.js, npm-shrinkwrap.json, package.json, webpack.config.js) z innego, działającego, projektu do folderu root projektu nadpisując istniejące.

Ważne aby node.js był w wersji np. 14.15.3 (tę mamy sprawdzoną, ale możliwe, że działają inne) z wyższymi jest problem z biblioteką od SASS (nie spawdzaliśmy od której, na 18 był problem). Link bezpośredni do node: https://nodejs.org/dist/v14.15.3/node-v14.15.3-x64.msi

Gdyby występował problem z SASS przy wykonaniu komendy "gulp" (*Error: Node Sass does not yet support your current environment: Windows 64-bit with Unsupported runtime (108)*) należy doinstalowac kompatybilną z node wersję sass (https://stackoverflow.com/questions/64612707/node-sass-does-not-yet-support-your-current-environment-windows-64-bit-with-uns):

npm uninstall node-sass
npm i sass

lub konkretnie wersję:

npm install node-sass@4.14.0