Aplikacja stanowi platformę do grupowej konsultacji projektów w różnych fazach ich rozwoju. Aplikacja działa w oparciu o technologie webowe, dokonuje synchronizacji z centralną instancją dzięki swoim modułom funkcjonalnym, działa zarówno on-line, jak i offline oraz obsługuje możliwość pracy na urządzeniach mobilnych. Praca użytkowników przebiega niezależnie, w środowisku ustalonym w ramach jednej konsultacji nad projektem. Istnieje możliwość kategoryzacji dyskusji nad projektem, głosowania, wystawiania ocen, załączania plików, komentarzy i innych, niezbędnych do realizacji celu jakim jest dyskusja nad danymi materiałami.
Instrukcja uruchomienia projektu lokalnie jest następująca:
-
Należy sklonować repozytorium:
git clone https://github.com/Fiooodooor/Programowanie_zespolowe_UMK.git
-
Pobieramy Pythona 3 i aktualizujemy menadżer pakietów
sudo apt install python3
sudo apt install python3-pip
pip3 install --user --upgrade pip
pip3 install --user virtualenv
-
Następnie aktywujemy środowisko wirtualne:
python3 -m virtualenv ENV
source ENV/bin/activate
pip install -r backend/requirements.txt
pip install gunicorn
-
Opcjonalnie konfigurujemy zmienne środowiskowe (media, static, debug mode, database url, etc).
cp .env_template .env
vim .env
-
Uruchamiamy serwer.
python3 backened/manage.py runserver
lub
gunicorn -b 127.0.0.1:8000 -b [::1]:8000 -w 4 backend.wsgi &
w drugim wypadku pamiętamy o zamknięciu procesu w tle po zakończeniu pracy lokalnie
/ │ README.md plik readme │ CHANGELOG.md plik changelog służący do monitorowania poważnych zmian w strukturze repozytorium │ │──── backend zawiera zasoby związane z warstwą dostępu do danych │ │ │ │─── backend │ │ │ │─── pznsi | | | |─── templates | │─── dbms zawiera zasoby związane z bazą danych i zarządzaniem nią | │─── docs pliki dokumentacji projektu │ │─── frontend zawiera zasoby związane z warstwą prezentacji │ │ │ │─── │ │ │ │─── │ │─── homepage zawiera zasoby związane ze stroną projektu na maszynie wydziałowej │ │─── mobile zawiera zasoby związane z aplikacją mobilną | │─── uix zawiera zasoby związane z opracowaniem interfejsu │ │─── temp pliki tymczasowe
- praca z repozytorium odbywa się na zasadach ogólnej pracy z kontrolą wersji GIT,
- nic nie stoi na przeszkodzie, aby używać zautoamtyzowanej kontroli wersji póki jest ona zgodna z niniejszym README.md,
- członkowie projektu pracują w obrębie swoich zadań wpisanych w Trello.
- master - instancja produkcyjna,
- test - instancja testowa,
- devel - instancja deweloperska.
Gałęzie są chronione - merge zmian jest możliwy dopiero po jego akceptacji w drodze Code Review.
Większe zmiany oraz numer aktualnej wersji będą zawierane w pliku CHANGELOG.md.
Zmiana to jakiekolwiek działanie na repozytorium polegające na zmianie jego zawartości lub struktury.
- zmiany muszą być wykonywane przez wydzielanie branchy z docelowej gałęzi instancyjnej i następnie, po zakończeniu pracy na branchu, przez skorzystanie z mechanizmu Merge Request (bezpośrednie wypychanie zmian do jednego z branchy instancyjnych bez akceptacji jest możliwe tylko w wyjątkowych sytuacjach),
- Merge Request polega na ocenie zmian (kodu, plików binarnych, wpisów do dokumentacji, plików graficznych etc.) z danego brancha i spokojnej wymianie pomysłów na ewentualne poprawki pracy,
- wydzielenie następuje z tej gałęzi instancyjnej, do której mają trafić zmiany (szerzej w kolejnych akapitach),
- Merge Request musi być tak przygotowany, aby nie tworzył konfliktu przy Merge oraz powinien być stosownie opisany,
- w związku z potencjalnie dużą ilością zmian, rozsądnym będzie zrezygnować z podziału innego niż trzy instancje i zbiorowe gałęzie, ponieważ już na etapie deweloperskim rodzi to potrzebę mergowania osobnego brancha złożonego z 'n' branchy do brancha devel, gdzie możemy bezpośrednio mergować je do niego (zamiast devel <- backend (branche x, y, z,), devel <- (branche x, y, z)).
Nazwa gałęzi tworzonej przez programistę musi być postaci:
[numer_zadania]_[directory_w_repozytorium]_[bardzo_zwiezly_opis]
numer_zadania - pełna dowolność oznaczenia z uwzględnieniem, że zadanie powinno być identyfikowalne (np. numer, inicjały, pseudonim - tak, aby oznaczenie miało odzwierciedlenie w konkretnym zadaniu umieszczonym w karcie na Trello).
directory_w_repozytorium - jest to ścieżka w repozytorium (ścieżka w nazwie nie wpływa na docelowe miejsce dodania zasobów do repozytorium, jest jedynie właściwością porządkującą).
bardzo_zwiezly_opis - maksymalnie 100 znaków, na przykład nagłówek zadania na danej karcie Trello.
Nie należy oznaczać gałęzi, jak i commitów, nazwami typu "aazzz", "12345", "bebebebe", "fofo1212" - utrudnia to identyfikację zadań podczas Code Review oraz istnieje realne niebezpieczeństwo pokrycia nazwy brancha lub commita z hashem istniejącego działania w repozytorium, co będzie skutkować zablokowaniem niektórych operacji podczas pracy z kontrolą wersji (na szczęście odwracalnym). Nie należy także używać polskich znaków i zaleca się ograniczenie użycia znaków specjalnych innych niż te przyjęte jako interpunkcyjne.
Przykłady:
alusz2b_backend_dodanie_mapowania_tabeli_users
dszczu_backend_skrypt_poprawiający_szyfrowanie
fiooodooor_mobile_dodanie_nowych_spinnerow
om12_dbms_skrypty_triggerow
mw_frontend_skalowanie_wyswietlania_ekranu_zespolow
W wypadku potrzeby dodania hotfixa lub poprawek w instancji testowej należy wydzielić tyle gałęzi ile jest to potrzebne (tj. 2-3) i wtedy dodać po oznaczeniu identyfikującym zadanie nazwę brancha instancyjnego:
[numer_zadania]_[directory_w_repozytorium]_[bardzo_zwiezly_opis]
Przykłady:
alusz102a_master_poprawka_w_oknie_formularza_oceny
alusz102a_test_poprawka_w_oknie_formularza_oceny
alusz102a_devel_poprawka_w_oknie_formularza_oceny
om12_test_dbms_poprawki_bezpieczenstwa
om12_devel_dbms_poprawki_bezpieczenstwa
Branche bez nazwy brancha instancyjnego to domyślnie branche wydzielone deweloperskie (devel).
- Dominik chce dodać skrypt optymalizujący dwie funkcje agregujące dane.
- Dominik przechodzi na DEVEL devel (pamiętając o komendzie *git pull) i wydziela z niego przykładowego brancha dszczu32a_backend_optymalizacja_funkcji_foo_i_bar,
- po zakończeniu pracy dodaje pliki do poczekalni komendą git add, a następnie commituje zmiany (treść commita powinna zwięźle opisać zmiany).
- Dominik używając stosownej komendy wypycha zmiany do repozytorium zdalnego pamiętając o squash-u commitów.
- Ostatnim krokiem jest utworzenie na Githubie Merge Request celem Code Review zespołu.
- Olaf zdał sobie sprawę, że istnieje dość istotny problem związany z bezpieczeństwem, który jest zlokalizowany w skryptach automatycznie czyszczących cache maszyny.
- Odnalazł podatność i przystąpił do pracy, która polegała na modyfikacji skryptów pracujących automatycznie po uruchomieniu serwisów.
- Wydzieli z brancha MASTER (pamiętając o komendzie *git pull) branch o nazwie omhf3_master_dbms_poprawka_skryptu_cache_w_kronie i przejdzie do niego.
- Zakończy w nim prace, które doda do poczekalni i wykona commit.
- Następnie zmieni brancha na TEST, wydzieli z niego brancha o nazwie omhf3_test_dbms_poprawka_skryptu_cache_w_kronie.
- Dokona mergu z branchem nadrzędnym komendą git merge omhf3_master_dbms_poprawka_skryptu_cache_w_kronie.
- Następnie powtórzy operację z branchem DEVEL, czyli wydzieli z brancha devel brancha omhf3_devel_dbms_poprawka_skryptu_cache_w_kronie i wykona git merge omhf3_test_dbms_poprawka_skryptu_cache_w_kronie.
- Olaf ostatecznie wypycha wszystkie branche do repozytorium zdalnego i tworzy Merge Request celem Code Review zespołu.
- Github po zamieszczeniu Merge Requestów do Code Review powinien pokazać stosowną ilość zmian względem każdego brancha (1 na masterze i odpowiednią ilość nowych zmian z branchy test i devel).
Praca na branchach master i test należy do sytuacji wpadkowych i nie powinna być regułą. Aby zapewnić spójność aplikacji zmiany powinny przechodzić pełną drogę instancyjną: devel -> test -> master.
Code Review jest wykonywane w zależności od danego modułu przez cały zespół lub przez osoby, które uczestniczą w jego tworzeniu na zasadzie wzajemnego informowania. Code Review mogą co do zasady wykonywać wszyscy, ale wskazane jest aby dla danego modułu uczestniczyły w nim obligatoryjnie następujące zestawy osób:
Dla backendu Alicja, Dominik, Olaf, Miłosz, Mateusz.
Dla frontendu Alicja, Dominik, Mateusz.
Dla bazy danych Olaf, Miłosz, Dominik, Alicja.
Dla aplikacji mobilnej Alicja, Dominik, Miłosz.
Dla UIX Olaf, Miłosz, Mateusz.
Dotyczy to zarówno kodu jak i dokumentacji.
- co najistotniejsze CAŁY kod i dokumentacja jest tworzona w języku angielskim - jedynym odstępstwem od reguły jest niniejsze README.md,
- poruszamy się w ramach konwencji danego frameworku (np. dla Pythona konwencje snake_case, korzystanie z PyLint i Flake, dla bazy danych ANSI SQL),
- zwracamy uwagę na znaki końca lunii zgodne z Unix podczas przygotowania skryptów (aby kontrola wersji nie wariowała przy edytowaniu na różnych platformach i systemach),
- kodowanie UTF-8,
- nazwy skryptów są co do zasady dowolne, jednak powinny albo w nazwach własnych albo w dokumentacji (a najlepiej w obu miejscach) mieć oznaczenie w jakiej kolejności powiny być wykonywane,
- stosujemy komentarze w kodzie oprócz samej dokumentacji,
- zabronione jest pozostawianie segmentów zakomentowanego kodu celem powtórnego wykorzystania lub przeprowadzania quasi-testów jednostkowych - wszelkie notatki powinny być trzymane poza repozytorium (lub w dokumentacji, jeżeli miałby to być obszerniejszy in-line comment), a testy są oddzielnym zasobem.
- aby ułatwić kontrolę wersji dokumentacja będzie sporządzona w plikach TEX,
- dokumentacja powinna być prowadzona szczegółowo (z rozbiciem na poszczególne obiekty).
W repozytorium powinny być umieszczane przede wszystkim pliki zawierające kod lub pliki niezbędne do jego uruchomienia (nie dotyczy to bibliotek zewnętrznych, plików binarnych, modułów nie mieszczących się w ramach projektu).
W repozytorium nie powinny znaleźć się:
- notatki,
- wireframe-y dla modułów innych niż UIX,
- szeroko pojęte helpery (linki do tutoriali, objaśnień zewnętrznych itd.), pliki wykonywalne pozostałe po kompilacji.
W wypadku, gdy nie można uniknąć takich elementów, powinny one znaleźć się w ścieżce /temp.
W repozytorium nie mogą znaleźć się:
- wszelkie materiały objęte prawami autorskimi(pomoce naukowe, zewnętrzny kod, zewnętrzne programy wykonywalne),
- niezaszyfrowane dane dotyczące dostępów(hasła, adresy maszyn, dane kontaktowe).
Paczki muszą być przygotowane (jako kod) i opisane (w dokumentacji) w taki sposób, aby wykonując odpowiednie kroki można było odtworzyć środowisko pracy dla aplikacji. Opis stawiania środowiska uruchomieniowego powinien być wykonany w taki sposób, aby była w stanie je odtworzyć osoba nie mająca pojęcia o projekcie (ze skryptami, odniesieniami do frameworków, bibliotek etc.).
Zasoby pozarepozytoryjne, czyli np. wireframe-y, notatki, credentiale, informacje o projekcie, helpery etc.) są przechowywane w zależności od ich charakteru na lokalnych stacjach roboczych członków zespołów lub na Trello.