Questa repository è relativa ai contenuti del corso di Ingegneria del Software dei prof. Carlo Bellettini e Mattia Monga, per l'anno accademico 2022/23.
Example [Jekyll] website using GitLab Pages. View it live at https://pages.gitlab.io/jekyll
Gli appunti sono presi in collaborazione secondo i principi dello sviluppo di software _open source_.
Contribuire non è solo un modo per studiare, ma anche per utilizzare Git e alcuni concetti dell'Ingegneria del Software in un contesto reale.
[Learn more about GitLab Pages](https://pages.gitlab.io) or read the the [official GitLab Pages documentation](https://docs.gitlab.com/ce/user/project/pages/).
I _maintainer_ ufficiali sono:
- Marco Aceti
- Daniele Ceribelli
- Matteo Mangioni
---
e gli altri contributori sono:
- Alessandro Mangili
- Alessandro Tellarini
- Armani Islam
- Mattia Oldani
- Silvio Angelo Settembrese
ma _chiunque_ può contribuire e proporre _Merge Request_.
Se utilizzi questi appunti per studiare, non solo è _galante_ contribuire ma è anche un modo per controllare e sistemare l'enormità di errori che prevediamo saranno presenti e per espandere o integrare nozioni e concetti.
I docenti del corso sono a conoscenza di questo progetto e sembrano apprezzarlo.
Tutti i contenuti saranno rilasciati sotto licenza [Creative Commons BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) dopo gli esami.
## Visualizzare
È possibile visualizzare gli appunti approvati sul branch `master` a questa pagina di GitLab Pages: https://silab-gang.gitlab.io/sweng.
## Contribuire
### Stack tecnologico
Tutti i contenuti sono scritti in Markdown e quindi convertiti in HTML autoamticamente da [Jekyll](https://jekyllrb.com/).
Le pagine su GitLab Pages sono automaticamente _compilate_ in HTML da un workflow di GitLab CI, ma solo quando approdano sul branch `master`.
Utilizziamo alcuni plugin di Jekyll per consentire di utilizzare LaTeX, immagini responsive e tabelle.
Per strutture complesse, è possibile embeddare dell'HTML (e del CSS) nel file Markdown.
Riferirsi al sito di Jekyll per installare Ruby e Jekyll a livello di sistema.
Una volta fatto, per installare i componenti necessari i seguenti comandi dovrebbero funzionare:
```bash
$ cd Cartella_Progetto
$ bundle install
$ bundle exec jekyll serve --livereload
```
Con l'ultimo comando aprendo la pagina https://localhost:4000/sweng nel nostro browser potremo visualizzare un'anteprima della pagina HTML compilata, aggiornata ad ogni modifica del file Markdown originale.
È estremamente consigliato arrivare a questo punto prima di continuare: non inviare patch prima di aver verificato che Jekyll compili il file in una pagina sensata.
Oltre a Jekyll, è naturalmente necessario avere Git installato sulla propria macchina.
Come editor di testo, consigliamo VSCode (meglio ancora [VSCodium](https://vscodium.com/)) ma qualsiasi va bene.
### Regole base di Git
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents***generated with [DocToc](https://github.com/thlorenz/doctoc)*
- Utilizziamo GitLab e non GitHub perché abbiamo iniziato con GitLab e non abbiamo motivo per cambiare.
- Abilita l'[autenticazione a due fattori](https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html).
- Consigliamo l'utilizzo dell'[autenticazione SSH](https://docs.gitlab.com/ee/user/ssh.html) con GitLab.
- Imposta il tuo nome e cognome reale; per esempio: `git config --global user.name "Carlo Bellettini"`;
- Utilizza la tua email universitaria, se vuoi; per esempio: `git config --global user.email "carlo.bellettini@unimi.it"`. Ricordati di aggiungere l'email al tuo account GitLab.
- Consigliamo di impostare e attivare la [firma dei commit](https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/) tramite GPG.
-[Getting Started](#getting-started)
-[Start by forking this repository](#start-by-forking-this-repository)
-[Start from a local Jekyll project](#start-from-a-local-jekyll-project)
-[GitLab CI](#gitlab-ci)
-[Using Jekyll locally](#using-jekyll-locally)
-[GitLab User or Group Pages](#gitlab-user-or-group-pages)
-[Did you fork this project?](#did-you-fork-this-project)
-[Other examples](#other-examples)
-[Troubleshooting](#troubleshooting)
### The _"Silab Gang" Notes Engineering Development Process_
Per ogni __argomento__ (spesso corrispondente a una _lezione_) N...

<!-- END doctoc generated TOC please keep comment hereto allow auto update -->
Ad ogni argomento corrisponde un file Markdown sotto la directory di Jekyll `_posts/`.
## Getting Started
#### Organizzazione dei branch
You can get started with GitLab Pages using Jekyll easily by either forking this repository or by uploading a new/existing Jekyll project.
La gestione dei branch è simile a GitFlow, ma non è uguale.
Osserviamo le tipologie di branch:
-`master`: contiene l'ultima versione stabile di tutti gli appunti. Ad ogni commit viene azionata una GitLab CI che aggiorna la pagina su GitLab Pages. Solo i maintainer possono mergiare su questo branch.
-`lezioni/N` (ma forse avremmo dovuto chiamarli `argomenti/N`): contiene l'ultima versione _instabile_ di uno specifico argomento.
I contributori della lezione `N` pulleranno dal branch `lezioni/N` per sincronizzare i contributi degli altri nel proprio branch, e mergieranno (o chiederanno di mergiare) i propri contributi nel branch `lezioni/N`. Nel nome c'è un _leading zero_: `lezioni/04`, `lezioni/12`.
- __branch utente__: iniziano con il nome dell'utente (lower case e breve) e sono utilizzati come _"sandbox"_ personale.
Remember you need to wait for your site to build before you will be able to see your changes. You can track the build on the **Pipelines** tab.
Tutti i branch devono essere creati partendo da `master`.
È consentito e apprezzato il fast forward in caso di merge banali.
### Start by forking this repository
Essendo i branch `lezioni/N` condivisi, è __NECESSARIO__ aggiornare il branch con il remoto facendo `git pull`. Prima di mergiare in `lezioni/N`, quindi:
1. entra nel branch `lezioni/N`: `git switch lezioni/N`;
2. scarica le ultime modifiche: `git pull`;
3. entra nel tuo branch: `git switch mio/branch`;
4. mergia il branch `lezioni/N`: `git merge lezioni/N`;
5. risolvi gli eventuali conflitti;
6. entra nel branch `lezioni/N`;
7. mergia il tuo branch: `git merge lezioni/N`;
8. carica le tue modifiche: `git push lezioni/N`.
1. Fork this repository.
1.**IMPORTANT:** Remove the fork relationship.
Go to **Settings (⚙)** > **Edit Project** and click the **"Remove fork relationship"** button.
1. Enable Shared Runners.
Go to **Settings (⚙)** > **Pipelines** and click the **"Enable shared Runners"** button.
1. Rename the repository to match the name you want for your site.
1. Edit your website through GitLab or clone the repository and push your changes.
> `lezioni/N` contiene sempre l'___ultima versione instabile___ e tutti i contributori la utilizzano come riferimento per quell'argomento.
> I contributi non mergiati in `lezioni/N` non saranno considerati da nessuno e sono quindi inutili.
> In ogni caso, non si committa mai direttamente a `lezioni/N` ma prima si passa sempre per un _branch utente_.
### Start from a local Jekyll project
#### Esempio
Lo studente Carlo Bellettini prende appunti durante la (sua?) lezione 5 e crea un branch `carlo/05-appunti`. Anche lo studente Mattia Monga prende appunti e pubblica le modifiche su `mattia/05-appunti`.
Carlo, da bravo contributore, si impegna a integrare gli appunti; crea il branch `carlo/05-integrazione` e mergia inanzitutto i suoi appunti (`carlo/05-appunti`) quindi quelli di Mattia (`mattia/05-appunti`).
1.[Install][] Jekyll.
1. Use `jekyll new` to create a new Jekyll Project.
1. Add [this `.gitlab-ci.yml`](.gitlab-ci.yml) to the root of your project.
1. Push your repository and changes to GitLab.
Il secondo merge da parte di Carlo degli appunti di Mattia causerà sicuramente dei conflitti, che Carlo dovrà risolvere: non è codice, è testo, e due studenti prenderanno gli appunti in modo completamente diverso!
Il concetto stesso di _integrazione_ è proprio questo.
## GitLab CI
Una volta terminato il lavoro, Carlo mergierà il suo branch `carlo/05-integrazione` in `lezioni/05`, quindi aprirà una Merge Request da `lezioni/05` verso il branch `master`.
This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
Inizia il processo di _review_: altri contributori (ovvero tutti a parte Carlo) controlleranno la correttezza e la __completezza__ (!) degli appunti proposti.
Se (ancora, per esempio) Marco trova dei problemi, può creare un proprio branch `marco/05-review` partendo dal branch `lezioni/05`, committare le proprie proposte e quindi rimegiarle in `lezioni/05`.
Infine, una volta che tutti i reviewer sono contenti, la Merge Request viene mergiata in master e gli appunti vengono aggiunti in GitLab Pages.
### Issues e Merge Requests
Per coordinare il lavoro tra di noi, utilizziamo principalmente la funzione "Issue" di GitLab.
Tutte le issues sono elencate [qui](https://gitlab.com/silab-gang/sweng/-/issues).
C'è una issue per ogni argomento. Ogni issue...
- ha un titolo con il numero (corrispondente all'`N` nei nomi di branch) e al nome dell'argomento;
- ha una descrizione, contentente i riferimenti alle lezioni relative all'argomento (come la data) e altre note opportune (_"il prof. ha spiegato il pattern Observer in questa lezione"_, ...);
- ha un label per tracciare lo stato nel processo (Da Fare / In esecuzione / In attesa di review / Fatto);
- ha un epico per tracciare il progresso dei [4 macro argomenti](https://gitlab.com/silab-gang/sweng/-/milestones/) del corso.
- ha un utente assegnato: solitamente è l'integratore principale della issue.
Nelle issue si può discutere e coordinare il lavoro, ma le review si fanno nelle merge request.
Le osservazioni sul _processo_ si fanno nell'issue, quelle sul _contenuto_ nella merge request.
Le merge request sono collegate alla relativa issue semplicemente citandola.
È possibile utilizzare la [revisione GitLab](https://docs.gitlab.com/ee/user/project/merge_requests/reviews/) per indicare i problemi: se trovi un problema sei invitato a risolverlo subito, per velocizzare il processo.
## Convenzioni Jekyll e di stile
Il Markdown scritto su Jekyll è particolare e richiede l'utilizzo di alcune convenzioni, specialmente per lavorare insieme.
Jekyll è orientato alla creazione di blog personali, quindi ogni _argomento_ (pagina) è, secondo la terminologia di Jekyll, un _blog post_.
Questo ha implicazioni fastidiose: per esempio, è necessario assegnare una data ad ogni _"post"_ anche se non ha molto senso se si sta parlando di appunti.
Per convenzione, per ogni _post_ utilizziamo sempre come data (e ora) quello della prima lezione in cui l'argomento è stato introdotto.
### Nomi di file e intestazione
Tutti i _post_ vanno creati nella cartella `_posts/`.
Ogni file all'interno di `posts/` DEVE avere come il seguente nome: `YYYY-MM-DD-titolo-argomento.md` dove YYYY-MM-DD è la __data__ del post in quel formato e `titolo-argomento` il titolo (breve) che comparirà nell'URL.
All'inizio di ogni post Markdown DEVE ESSERE PRESENTE il _Jekyll header_.
Di seguito un esempio:
```
image: ruby:2.3
variables:
JEKYLL_ENV: production
pages:
script:
- bundle install
- bundle exec jekyll build -d public
artifacts:
paths:
- public
only:
- master
---
layout: post
title: "[01] Introduzione"
date: 2022-10-03 14:30:00 +0200
toc: true
---
```
## Using Jekyll locally
Il numero nel titolo racchiuso tra parentesi quadre deve essere uguale al numero di argomento N assegnato nell'issue e nei nomi di branch.
Il parametro `toc: true` serve per generare automaticamente la Table Of Contents all'inizio del file HTML compilato.
To work locally with this project, you'll have to follow the steps below:
Se non vedete un post che avete creato sul vostro Jekyll, molto probabilmente state sbagliando una di queste convenzioni.
1. Fork, clone or download this project
1.[Install][] Jekyll
1. Download dependencies: `bundle`
1. Build and preview: `bundle exec jekyll serve`
1. Add content
È possibile che durante la prima fase di presa degli appunti durante la lezione vengano utilizzati dei nomi di file diversi.
È compito degli integratori sceglierne uno adatto e degli altri contributori adottarlo.
The above commands should be executed from the root directory of this project.
### Stile di scrittura
Read more at Jekyll's [documentation][].
Cerca di essere chiaro, conciso ma __completo__.
È chiaro che all'esame viene chiesto _tutto_, compresi i riferimenti esterni: durante la fase di integrazione occorre quindi includere ogni nozione e concetto rilevante.
## GitLab User or Group Pages
L'obiettivo è creare la _bibbia_ del corso: idealmente studiandola da zero si dovrebbe arrivare al 30L.
To use this project as your user/group website, you will need one additional
step: just rename your project to `namespace.gitlab.io`, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
Evita quindi di:
- citare concetti senza spiegarli;
- dare per scontato conoscenze (_"su git si possono fare i commit"_ => _"su git si può utilizzare `git commit` per creare un commit"_);
- ricopiare i contenuti pari pari alle slide;
- scrivere "..." alla fine degli elenchi puntati;
- ...
Read more about [user/group Pages][userpages] and [project Pages][projpages].
Naturalmente, queste indicazioni valgono per gli appunti proposti per il branch master: per gli appunti presi a lezione è assolutamente OK essere vaghi o brevi.
## Did you fork this project?
### Immagini
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
Per includere immagini utilizziamo il plugin `jekyll-responsive-image`, che le ottimizza per tutti i dispositivi.
## Other examples
Le immagini sono da mettere nella cartella `assets/` e tracciate con Git (altrimenti gli altri non le vedranno!).
Per convenzione nostra, i nomi dei file immagine è `N_nome-immagine.png` dove `N` è il numero di lezione giù più volte citato in questa guida.
*[jekyll-branched](https://gitlab.com/pages/jekyll-branched) demonstrates how you can keep your GitLab Pages site in one branch and your project's source code in another.
* The [jekyll-themes](https://gitlab.com/groups/jekyll-themes) group contains a collection of example projects you can fork (like this one) having different visual styles.
Per includere un'immagine, è sufficiente inserire nel Markdown la seguente stringa e Jekyll si occuperà ad inserire l'immagine.