Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

--- gwusermanual:handlerepository [2023/05/15 21:59]
giada.podelvento [Creazione struttura cartelle di base]
+++ gwusermanual:handlerepository [2023/05/19 16:08] (versione attuale)
giada.podelvento
@@ Linea 1: / Linea 1: @@
-====== Reporisoty di Progetto ======
+====== Repository di Progetto ======
@@ Linea 62: / Linea 62: @@
 Una volta creato il [[gwusermanual:handlerepository#creazione_del_repository_remoto|repository remoto]] e averlo [[gwusermanual:handlerepository#creazione_del_repository_locale|clonato in locale]] è necessario dotare il progetto di una struttura specifica, adottata per convenzione, in modo tale che le risorse possano essere usate correttamente dai vari file eseguibili messi a disposizione per dispiegarle in maniera semiautomatica.
-La prima cosa da fare è cliccare sul seguente {{ :gwusermanual:progetto-template.zip |link}} e avviare il download della cartella ZIP contenente la struttura iniziale delle cartelle.  Al termine del download copiare il file zip nella cartella principale del repository locale (dove è già presente il file .git) e decomprimere qui il file. Una volta decompressa avremo così la seguente struttura {{ :gwusermanual:struttura_progetto_1.jpg?nolink |}}
+La prima cosa da fare è cliccare sul seguente {{ :gwusermanual:progetto-template.zip | link}}  e avviare il download della cartella ZIP contenente la struttura iniziale delle cartelle.  Al termine del download copiare il file zip nella cartella principale del repository locale (dove è già presente il file .git) e decomprimere qui il file. Una volta decompressa avremo così la seguente struttura {{ :gwusermanual:struttura_progetto_1.jpg?nolink |}}
 Di seguito riportiamo una breve descrizione di tutte le cartelle qui contenute.
@@ Linea 112: / Linea 112: @@
 ----
-=== FILE pom.xml DI PROGETTO ===
+=== FILE pom.xml ESTERNO ===
-Con file **pom.xml** di progetto ci si riferisce all'omonimo file contenuto nel repository git ed evidenziato nell'immagine seguente: {{ :gwusermanual:struttura_progetto_2_pom_di_progetto.jpg?nolink |}}
+Con file **pom.xml esterno** ci si riferisce all'omonimo file contenuto nel repository git, contenente le configurazioni maven di progetto, ed evidenziato nell'immagine seguente: {{ :gwusermanual:struttura_progetto_2_pom_di_progetto.jpg?nolink |}}
 Questo file contiene informazioni essenziali sul progetto, viene letto da Maven durante la build prendendo le informazioni presenti per scaricare le dipendenze necessarie, compilare il codice sorgente e generare l'output desiderato (quindi il pacchetto WAR).
@@ Linea 138: / Linea 138: @@
 Tutto ciò che è contenuto sotto la stringa ''<!-- NON MODIFICARE -->'' non necessita variazioni.
 Salvare le modifiche apportare e chiudere l'editor di testo.
+<color #ed1c24>**ACHTUNG!!**</color> Ricordarsi di aggiornare la versione di questo file (tag "version") quando si esegue un rilascio!!!
 ----
@@ Linea 191: / Linea 193: @@
 Le modifiche apportate ai vari file dipendono dal progetto, ma anche dall'ambiente in cui il progetto deve essere utilizzato, per qualsiasi dubbio rivolgersi alla sezione sviluppo
+----
+=== File ReleaseNotes.md ===
+Il file **ReleaseNotes.md** è un documento di testo formattato in formato Markdown ([[https://www.liberliber.it/progetti/manuzio/collaborare/manuale_markdown_20201226.pdf | Manuale]]) che contiene le note di rilascio del progetto. Le note di rilascio forniscono informazioni sugli aggiornamenti, le correzioni di bug, le nuove funzionalità e altre modifiche apportate nella versione specifica rilasciata.
+Alla prima apertura, il file presenta pochissime informazioni riassunte nel box di seguito
+<code>
+# Project Name - Release Notes
+## Version X.X.X
+Release Date: YYYY/MM/DD
+### Features
+### Bugfix
+### Deprecation and Removal
+</code>
+  * **Project Name** è il nome del progetto. Può coincidere con il nome del repository git
+  * **Version X.X.X** è la versione rilasciata. Sostituire X.X.X con la versione rilasciata. Le regole di versioning sono consultabili [[gwusermanual:handlerepository#regole_base_di_versionamento|qui]]
+  * **Release Date: YYYY/MM/DD** rappresenta la data di rilascio. Sostituire YYYY/MM/DD con la data del giorno in cui si esegue il rilascio
+  * **Features** contiene un elenco puntato delle nuove funzionalità aggiunte nella versione specifica oggetto di rilascio. Questa sezione fornisce una panoramica delle principali migliorie e aggiunte che gli utenti possono aspettarsi di trovare dopo l'aggiornamento. Le descrizioni delle nuove funzionalità spesso includono una breve spiegazione di cosa fanno e come possono essere utilizzate dagli utenti, senza entrare nel merito dei dettagli tecnici.
+  * **Bugfix** contiene informazioni sugli errori o problemi noti che sono stati risolti nella versione specifica oggetto di rilascio. Questa sezione elenca i bug o le anomalie che sono stati identificati e risolti: ogni voce di bugfix solitamente include una descrizione del problema risolto, i passi necessari per riprodurlo, e come è stata affrontata la correzione. Fornisce agli utenti una visione delle correzioni di bug apportate e degli eventuali problemi risolti per migliorarne la stabilità e l'esperienza utente.
+  * **Deprecation and Removal** indica le funzionalità, le API o altri componenti che sono stati contrassegnati come deprecati o rimossi nella versione specifica oggetto di rilascio. La deprecazione indica che una determinata funzionalità o componente è stata dichiarata obsoleta e verrà probabilmente eliminata nelle future versioni. Vengono inoltre fornite le informazioni sulle funzionalità deprecate o rimosse suggerendo, quando possibile, soluzioni alternative o sostitutive che possono essere utilizzate al loro posto.
+Ogni volta che viene eseguito un rilascio, è importante aggiornate le note di release, aggiornare il tag "version" sul [[gwusermanual:handlerepository#file_pomxml_esterno|pom esterno]] e seguire le regole di tag del repository descritte [[gwusermanual:handlerepository#rilascio_versione_e_tag|qui]]
+===== Sincronizzare con il repository remoto =====
+Prima di continuare, verificare di avere Fork installato sul proprio PC ([[gwinstguide:idxinstguide:installazione_fork|procedura di installazione]]).
+Una volta creato il repository remoto, clonato in locale e creato la struttura base delle directory, è importante assicurarsi che entrambi contengano le stesse modifiche e informazioni, cioè mantenerli sincronizzati.
+Quando si sincronizza un repository remoto e locale, significa che si sta facendo in modo che entrambi abbiano gli stessi cambiamenti. Ad esempio, se si è fatto delle modifiche al repository locale, si devono inviare ([[gwinstguide:idxinstguide:installazione_fork#push|push]]) tali modifiche al repository remoto affinché le altre persone possano vederle.
+Allo stesso modo, se qualcun altro ha fatto delle modifiche nel repository remoto, dovremmo ottenere ([[gwinstguide:idxinstguide:installazione_fork#pull|pull]])  tali modifiche nel nostro repository locale per assicurarci di avere la versione più aggiornata.
+In sostanza, sincronizzare un repository remoto e locale significa __mantenere i due repository allineati__ in modo che contengano le stesse informazioni e modifiche più recenti. Ciò consente a tutti i collaboratori di lavorare con le ultime versioni dei file, mantenere la coerenza del progetto e gestire al meglio lo storico delle modifiche ai singoli file.
+Alcuni dei comandi principali di Fork sono descritti [[gwinstguide:idxinstguide:installazione_fork#comandi_principali|qui]].
+----
+=== Primo commit ===
+  - Aprire **Fork**
+  - Selezionare **File** => **Open Repository** {{ :gwinstguide:idxinstguide:open_repo_fork.jpg?nolink |}}
+  - Scegliere la cartella con il repository GIT da importare
+  - Fare click su **Seleziona cartella**
+  - Selezionare sulla sinistra in alto **Local Changes** (a destra verrà mostrato un numero tra due parentesi tonde che sta ad indicare il numero di modifiche e il numero di nuovi file e cartelle create o modificati nella cartella del repository locale)
+  - Nella sezione **Unstaged** selezionare in alto l'icona {{:gwusermanual:stage-all.jpg?nolink&30|}} per **stage all** (saranno selezionati TUTTI i file oggetto di modifica. Ad eccezione di quelli esclusi dal file [[gwusermanual:handlerepository#file_gitinore|.gitignore]])
+  - Scrivere un opportuno messaggio di commit. Normalmente il primo commit contiene per buona pratica il testo "first commit"
+  - Cliccare su **Commit** {{ :gwusermanual:first-commit.jpg?nolink |}}
+  - Verrà automaticamente generato il branch **main** ((Attenzione: dal 2022 il branch di riferimento di GIT è il branch **main** e non più il branch **master**. È solo un cambio di nome perchè “master” non è un termine “inclusivo”… Per i vecchi progetti può continuare ad essere utilizzato “master”))
+----
+=== GitFlow ===
+**Gitflow** è un modello di branching e workflow per la gestione dei repository GIT, che offre una struttura ben definita per organizzare il flusso di lavoro e gestire le modifiche nel repository.
+Il Gitflow si basa sulla creazione di diversi branch (rami di lavoro) con scopi specifici. Ecco una panoramica dei principali branch utilizzati nel Gitflow che adotteremo nel nostro specifico flusso di lavoro:
+  - ** Branch "main" o "master"**: Rappresenta il branch principale del repository, contenente le versioni rilasciate.
+  - **Branch "develop"**: È il branch di sviluppo principale, dove vengono integrate le nuove funzionalità e le modifiche non ancora pronte per il rilascio.
+  - **Branch "release"**: Quando il lavoro sul branch "develop" raggiunge uno stato stabile e pronto per il rilascio, viene creato un branch "release/X.X.X" essendo X.X.X la versione in corso di rilascio. In questo branch, vengono effettuati i test e le preparazioni per la distribuzione del progetto. Una volta completato, il branch "release/X.X.X" viene integrato sia nel branch "main" (o "master") che nel branch "develop" attraverso la procedura di **merge**.
+Il Gitflow definisce regole chiare su come e quando integrare i branch e promuovere le modifiche attraverso il flusso di lavoro. Ciò aiuta a mantenere la stabilità del codice, a facilitare la collaborazione tra i membri del team, a fornire una struttura organizzativa chiara nel processo di sviluppo del software gestendo al meglio e puntualmente le modifiche oggetto di ogni commit.
+{{ :gwusermanual:gitflow-repo-project.jpg?nolink |}}
+----
+=== Creazione del branch «develop» ===
+Per la creazione del branch **develop** seguire i passi seguenti:
+  - In **Fork** selezionare con il pulsande destro del mouse il **branch main** (o **master**)
+  - Cliccare su **New Branch…**
+  - In corrispondenza di **Branch name** digitare **develop**
+  - selezionare **Create and Checkout** {{ :gwusermanual:create-develop-branch.jpg?nolink |}}
+A questo punto il branch corrente è **develop** (un segno di spunta ✓ comparirà accanto al nome del branch), il repository remoto e locale sono allineati, perciò si può procedere con gli sviluppi ed eseguire tutti i commit necessari dal branch corrente, fino al termine dello sviluppo. Una volta terminato si è pronti per fare il primo rilascio.
+----
+=== Creazione del branch «release» ===
+ Quando il lavoro sul branch "develop" raggiunge uno stato stabile e pronto per il rilascio, creare un branch **release** consente di focalizzarsi sulla stabilizzazione delle funzionalità. In questo modo, è possibile effettuare gli ultimi test e preparazioni per il rilascio senza interferire con lo sviluppo delle nuove funzionalità in corso.
+  -In Fork accertarsi di essere posizionati sul branch develop (a sinistra del nome develop c’è un segno di spunta ✓)
+  - Assicurarsi di aver committato TUTTE le modifiche in locale (a sinistra Local Changes non presenta numeri tra parentesi tonde)
+  - Selezionare con il pulsande destro del mouse il **branch develop**
+  - Cliccare su **New Branch…**
+  - In corrispondenza di **Branch name** digitare **release/1.0.0** dove 1.0.0 dovrà ogni volta essere sostituito dalla versione in corso di rilascio
+  - Selezionare **Create and Checkout** {{ :gwusermanual:release_branch.jpg?nolink |}}
+----
+=== Rilascio versione e Tag ===
+Una volta eseguito il collaudo e ultimati i test, solo dopo aver ricevuto l'ok, è possibile rilasciare la versione e creare il tag nel repository GIT.
+  - In **fork**, fare doppo click sul **branch main o master** (aspettare che il simbolo di check ✓ si posizioni a sinistra di master)
+  - Click con il pulsante destro del mouse sul branch di release che si vuole rilasciare (//Esempio: release/1.0.0//)
+  - Selezionare **Merge into ‘master’…**{{ :gwusermanual:merge_release_dentro_master.jpg?nolink |}}
+  - Andare su tags (in basso a sinistra), fare click con il pulsante destro del mouse e scegliere **New tag**
+  - In corrispondenza di **Tag Name** digitare il numero di versione rilasciata
+  - Assicurarsi di aver selezionato **Push** (serve per pubblicare il tag anche sul repository remoto)
+  - Cliccare su **Create and Push** {{ :gwusermanual:tag_new.jpg?nolink |}}
+  - Fare doppio click sul branch **develop**
+  - Click con il pulsante destro del mouse sul branch di release appena rilasciata (//Esempio: release/1.0.0//)
+  - Selezionare **Merge into ‘develop’…**
+  - Cliccare **Push**
+Ad ogni rilascio deve corrispondere un tag corrispondente alla versione rilasciata.
+----
+=== Regole base di versionamento ===
+Le regole di versionamento dei rilasci possono variare a seconda del contesto e delle preferenze del progetto. Tuttavia, esistono alcune convenzioni comuni che possono essere seguite per gestire il versionamento dei rilasci del progetto. In particolare si è scelto di adottare il sistema di [[https://www.elbuild.it/tecnologie/gitflow.html | versionamento semantico]]  (Semantic Versioning), che prevede il formato **"MAJOR.MINOR.PATCH"**.
+Le regole di incremento sono le seguenti:
+   - Incremento del numero **MAJOR** quando vengono apportate modifiche incompatibili con la versione precedente.
+   - Incremento del numero **MINOR** quando vengono aggiunte nuove funzionalità in modo retrocompatibile.
+   - Incremento del numero **PATCH** quando vengono effettuate correzioni di bug retrocompatibili.
-===== Installazione di Fork =====