Merge pull request #1 from Toniolo-Marco/organization-and-roles

Organization and roles

.github/workflows/build-release.yml

@@ -0,0 +1,51 @@
+name: Build & Release
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+  workflow_dispatch:
+
+jobs:
+  Build_And_Release:
+    runs-on: [self-hosted, typst]
+    steps:
+      - name: Checkout
+        id: checkout
+        uses: actions/checkout@v4
+
+      - name: Compile LaTeX document
+        id: compile
+        shell: bash
+        run: |
+          # compile the main file
+          typst compile --root=./ --font-path=./src/fonts/segoe-ui-this src/main.typ git-for-dummies.pdf
+
+      - name: Delete previous release
+        id: deletePreviuosRelease
+        if: steps.compile.outcome == 'success'
+        continue-on-error: true
+        shell: bash
+        run: |
+          # Get the latest release ID
+          LATEST_RELEASE_ID=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/${{ github.repository }}/releases/latest | jq -r '.id')
+
+          # Delete the latest release
+          if [ "$LATEST_RELEASE_ID" != "null" ]; then
+            curl -s -X DELETE -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" "https://api.github.com/repos/${{ github.repository }}/releases/$LATEST_RELEASE_ID"
+          else
+            echo "No previous release found."
+          fi
+
+      - name: Publish Release
+        id: release
+        if: steps.compile.outcome == 'success'
+        uses: svenstaro/upload-release-action@v2
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          file: ${{ github.workspace }}/git-for-dummies.pdf
+          asset_name: Git-for-Dummies.pdf
+          overwrite: true
+          body: "Brief introduction to using git, GitHub and managing an organization for Professor Patrignani's Advanced Programming course"
+          release_name: "Git for Dummies"

docker/typst/Dockerfile

@@ -0,0 +1,32 @@
+# Use GitHub Actions Runner as the base image
+FROM debian:stable-slim
+
+ADD ./runner runner
+
+WORKDIR /runner
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+SHELL ["bash", "-c"]
+
+RUN ./bin/installdependencies.sh && apt-get install -y xz-utils jq curl  && apt-get autoclean && apt-get autoremove --yes && rm -rf /var/lib/{apt,dpkg,cache,log}/
+
+# Install Typst
+RUN curl -L https://github.com/typst/typst/releases/latest/download/typst-x86_64-unknown-linux-musl.tar.xz -o typst.tar.xz \
+    && tar -xf typst.tar.xz \
+    && mv typst-x86_64-unknown-linux-musl/typst /usr/local/bin/ \
+    && rm -rf typst.tar.xz typst-x86_64-unknown-linux-musl
+
+# Verify Typst installation
+RUN typst --version
+
+ADD --chmod=754 ./start.sh start.sh
+
+ENTRYPOINT ["bash", "-c", "./start.sh"]
+
+ENV RUNNER_MANAGER_TOKEN=""
+ENV RUNNER_NAME=""
+ENV REPO_NAME=""
+ENV REPO_OWNER=""
+ENV ACTIONS_RUNNER_INPUT_REPLACE=true
+ENV RUNNER_ALLOW_RUNASROOT=true

docker/typst/build-img.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+IMAGE_NAME="typst-runner:latest"
+
+case $(uname -m) in
+    x86_64)
+        ARCH="x64"
+        ;;
+    aarch64)
+        ARCH="arm64"
+        ;;
+    *)
+        echo "Unsupported architecture"
+        exit 1
+        ;;
+esac
+
+echo "retrieving latest version number from release page"
+LATEST=`curl -s -i https://github.com/actions/runner/releases/latest | grep location:`
+LATEST=`echo $LATEST | sed 's#.*tag/v##'`
+LATEST=`echo $LATEST | sed 's/\r//'`
+echo "downloading latest GitHub runner (${LATEST})"
+
+curl --progress-bar -L "https://github.com/actions/runner/releases/download/v${LATEST}/actions-runner-linux-${ARCH}-${LATEST}.tar.gz" -o runner.tgz
+
+mkdir -p runner
+
+echo "unpacking runner.tgz"
+tar -zxf runner.tgz -C runner
+
+docker build -t ${IMAGE_NAME} .
+
+echo "cleaning"
+rm -rf runner runner.tgz

docker/typst/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  typst-runner:
+    image: typst-runner:latest
+    container_name: typst-runner
+    restart: always
+    labels:
+      - "com.centurylinklabs.watchtower.enable=false"
+    volumes:
+      - /etc/localtime:/etc/localtime:ro
+    environment:
+      - RUNNER_MANAGER_TOKEN=
+      - RUNNER_NAME=typst-runner
+      - REPO_OWNER=Toniolo-Marco
+      - REPO_NAME=git-for-dummies

docker/typst/start.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+set -eux
+
+: $REPO_NAME
+: $REPO_OWNER
+: $RUNNER_MANAGER_TOKEN
+: $RUNNER_NAME
+
+# fetch a short-lived runner registration token for the org
+reg_token=$(curl -L \
+  -X POST \
+  -H "Accept: application/vnd.github+json" \
+  -H "Authorization: Bearer $RUNNER_MANAGER_TOKEN" \
+  https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/actions/runners/registration-token | jq -r .token)
+
+/bin/bash config.sh --unattended --url https://github.com/${REPO_OWNER}/${REPO_NAME} --name ${RUNNER_NAME} --work _work --token ${reg_token} --labels typst,self-hosted
+
+remove () {
+  local rem_token=$(curl -L \
+  -X POST \
+  -H "Accept: application/vnd.github+json" \
+  -H "Authorization: Bearer $RUNNER_MANAGER_TOKEN" \
+  https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/actions/runners/remove-token | jq -r .token)
+
+  ./config.sh remove --token $rem_token
+}
+
+trap remove EXIT
+
+./bin/runsvc.sh

src/cover.typ

@@ -11,7 +11,7 @@ align(horizon + left)[
   Toniolo Marco, Frigerio Federico
 ]
 
-align(bottom + left)[UniTn: Advanced Programming]
+align(bottom + left)[University of Trento, Advanced Programming course]
 
 // #align(bottom + left)[#datetime.today().display()]
 }

src/organization.typ

@@ -1,5 +1,43 @@
 = Organization
-
 L'organizzazione è un'account condiviso da più utenti dove è possibile collaborare su uno o più progetti, definendo ruoli e funzioni.
 Utilizzando le organizzazioni è possibile creare una suddivisione che rispecchia quella in classe, dove il *Working group coordinator* ha tutti i permessi 
-i *Git Maintainer* possono creare, modificare, accettare, rifiutare le pull request e scrivere ed eseguire delle Actions (di cui parleremo più avanti).
+i *Git Maintainer* possono creare, modificare, accettare, rifiutare le pull request e scrivere ed eseguire delle Actions (di cui parleremo più avanti) e tutti gli altri possono aprire issue, fare fork e creare delle pull request.
+
+== Creare un'organizzazione
+Per creare un'organizzazione recatevi sulla homepage di GitHub dopo aver fatto il login col vostro account, cliccate sul vostro nome utente (vicino alla foto) nell'angolo in alto a sinistra, e poi su crea organizzazione. Vi si aprirà la pagina coi piani, selezionate quello gratuito, poi compilate il form con i dettagli prestando attenzione a selezionare che l'organizzazione appartiene al vostro account personale e non ad un'azienda.
+
+== Creare i gruppi
+GitHub per gestire i permessi nelle organizzazioni fa uso dei gruppi, un gruppo è un insieme di utenti, ad ogni gruppo sono associati dei permessi, gli utenti di un gruppo ereditano i permessi.
+Per creare i gtuppi, cambiate dal vostro account a quello dell'organizzazione, se non lo avete già fatto, cliccando sempre sul vostro nome e selezionando quello dell'organizzazione, poi spostatevi su *Teams*, e create i seguenti gruppi:
+
+- Organization Owners
+- Members
+- Tutors
+
+=== Organization Owners
+Composto dal Working group coordinator e dai Git Maintainers, questo gruppo *deve avere tutti i permessi*, i membri di questo gruppo devono essere manualmente 
+impostati come Owners dell'organizzazione andando su *people*, cliccando sui *tre pallini* e poi su *cambia ruolo* e in fine *owner*. In questo modo, avranno pieni poteri su tutta l'organizzazione.
+
+=== Members
+Questo gruppo, deve poter forkare, creare issue e pull request sul repository del common crate, il ruolo da associarvi è Triage ma solo sul singolo repository 
+dopo vi spiegheremo come fare, per ora create il gruppo e non aggiungete membri, visto che sarete in \~100/150 persone è impensabile che qualcuno aggiunaga manualmente tutti i partecipanti, per questo si userà l'inviter, come spiegato successivamente.
+
+=== Tutors
+Questo gruppo avrà acesso in lettura al repository, conterra i tutors i quali andranno aggiunti manualmente in base al loro interesse, alcuni vi chiederanno di entrare e altri invece no, anche qui, il i permessi del gruppo vanno impostati sul singolo repository.
+
+== Il repository
+Create adesso il repository contenente il codice del Common Crate, come visibilità mettete private (il professore vi spiegherà che è per evitare che i futuri studenti trovino tutto pronto), le altre opzioni sceglietele in base 
+alle vostre preferenze. Una volta creato andate in *impostazioni*, poi *collaboratori e teams* e cliccate *aggiungi teams*, cercate *Organization Owners* e come ruolo assegnategli *Admin*. Ripetete per i *Members* e come ruolo 
+scegliete *Triage*, per ultimo il gruppo *Tutors* ai quali va il ruolo di *Read*.
+
+== Workflow consigliato
+Lo scorso anno, abbiamo provato a mimare l'approccio utilizzato dai grandi progetti open source per la gestione dei repository, questo cosisteva nelle seguenti fasi
++ Apertura di una issue
++ Votazione (se si tratta di una feature proposta)
++ Fork del repository
++ implentazione
++ Apertura di una pull request associata alla issue
++ Revisione
++ Merge nel main
++ Pubblicazione della nuova versione
+

src/roles-duties.typ

@@ -6,16 +6,30 @@ Una divisione tipica dei ruoli è:
 - Group Leader
 - Git Maintainer
 - Tester
-- Doc Writer
+- Reporter
 - Member
 
-=== Working group coordinator
+== Working group coordinator
 È il responsabile di tutta la parte comune del progetto, è lui che ha l'ultima parola su come interpretare le specifiche fornite dal prof, gestire le riunioni, 
 accettare o rifiutare le proposte (anche se è comune indirre delle votazioni), fissare le scadenze e scrivere report sullo stato del progetto dopo ogni riunione... 
 in pratica è il Linus Torvalds del progetto (aspettatevi la stessa gentilezza nelle risposte alle domande banali e al cattivo codice). È eletto a maggioranza dai membri presenti
 durante una delle prime lezioni, il docente di solito avvisa quando è la data dell'elezione.
 
-Il primo compito del WGL è quello di scegliere i suoi collaboratori, in primis i *Git Maintainers* (solitamente 2), i *Testers* (solitamente 3/4) e i *Doc Writer* (solitamente 2), fatto 
-questo il assieme ai GM, deve creare l'organizzazione e dare ad essi tutti i permessi, questo gli permetterà di delegare una buona mole di lavoro.
+Il primo compito del WGL è quello di scegliere i suoi collaboratori, in primis i *Git Maintainer* (solitamente 2), i *Tester* (solitamente 2/3) e i *Reporter* (solitamente 2), fatto questo il assieme ai GM, deve creare l'organizzazione e dare ad essi tutti i permessi, questo gli permetterà di delegare una buona mole di lavoro.
 
-Il secondo compito è quello d
+== Group Leader
+Ogni gruppo ha un responsabile, questo va scelto tra i membri e comunicato al docente entro la data stabilita assieme al nome del gruppo e all'elenco dei 
+partecipanti. Il suo compito è quello di partecipare alle riunione generali con WGL e di rappresentare gli interessi del gruppo, votando le varie questioni.
+
+== Git Maintainer
+Si consiglia di scegliere qualcuno che ha dimestichezza con git e GitHub. Si occuperà di gestire il repository, l'organizzazione su GitHub, setuppare l'inviter (o in alternativa aggiungere a mano tutte le persone), creare le action e cosa più importante gestire le issue, milestones e pull requests che verranno create, lavorerà in stretto contatto con i principali sviluppatori del *Common Crate* e coi testers. È compito suo accertarsi che una pr non rompa tutto il codice già presente o in caso contrario, che ci sia un valido motivo, deve controllare che il codice rispetti gli standard decisi e che sia ben documentato.
+
+== Tester
+Solitamente 2/3 persone, si occupano di scrivere i test che il Common Crate deve superare quando si implementa una nuova feature, oltre a scrivere i test che le applicazioni dei gruppi devono superare per verificare che stiano usando il Common Crate nel modo corretto, forzando gli standard decisi dalle specifiche.
+L'idea è che ad ogni pull request vengano eseguiti i test e in base all'esito di essi si procede con la revisione manuale.
+
+== Reporter
+Sono coloro che partecipano ad ogni riunione col compito di stilare un resoconto degli eventi, utile per tracciare i progressi e la direzione del progetto, basandosi su esso il WGL, stilerà il suo report da inviare al docente. Hanno inoltre il compito di scrivere le specifiche man mano che vengono corrette e definite.
+
+== Member
+Sono tutti i membri dei vari gruppi, il loro compito è partecipare all'implementazione del Common Crate, proporre feature e aprire pull requests con i cambiamenti proposti.