GitBook e la documentazione


La documentazione di Radical è stata finalmente migrata dal Wiki di GitHub ad uno strumento pensato per gestire la documentazione: GitBook.

Il risultato è disponibile qui: https://docs.radicalframework.com/.
I sorgenti sono invece su GitHub: https://github.com/RadicalFx/documentation.

Perché migrare.

Tre motivi principali:

  1. Il Wiki di GitHub è molto limitato in termini di feature, struttura della documentazione stessa e gestione degli asset
  2. L’aspetto collaborativo tipico di un progetto open source è monco. Ad esempio non c’è supporto per le PR, limitando quindi di fatto la possibilità che la community partecipi
  3. Originariamente Radical era un singolo progetto in un singolo repository e il Wiki soddisfava le necessità del tempo. Il progetto è evoluto, adesso ha la sua Organization su GitHub e il codice è stato separato in diversi repository. A questo punto ci siamo trovati in una situazione alquanto scomoda perché il repository originale non conteneva più tutto il codice ma conteneva tutta la documentazione.

La decisione è stata quindi quella di trovare una soluzione che cercasse di risolvere tutti i problemi.

Requisiti

Abbiamo quindi posto alcuni paletti:

  • Il repository deve essere un repository di GitHub
  • Il formato della documentazione deve essere
    • markdown
    • il più indipendente possibile dal tool usato per pubblicare la documentazione stessa
  • Supporto per la ricerca
  • Supporto per ToC

Il primo tentativo è stato fatto costruendo una roba completamente custom con Jekyll ma la ricerca e la generazione della ToC sono una rogna, insormontabile la prima, e noiosissima la seconda soprattutto considerando le limitazioni imposte dall’hosting di Jekyll nelle GitHub Pages.

Il secondo tentativo è stato Read the Docs che al primo colpo ha funzionato bene, poi le build hanno cominciato a fallire senza motivo. Il problema è che far gira tutto in locale, come ad esempio si fa con Jekyll, è abbastanza rognoso su Windows e la difficoltà di debug era tale che ho pensato di cercare altro.

Benvenuto GitBook

Alla fine devo dire che nel complesso l’esperienza GitBook è buona:

  • La sorgente primaria delle informazioni è GitHub
  • Tutto il flusso di GitHub è rispettato. Quindi una eventuale PR al momento della merge avvia la build della documentazione, etc
  • il linguaggio è markdown senza nessuna estensione particolare
  • c’è il supporto per la ricerca e la generazione della ToC

Ci sono anche dei bonus come ad esempio il fatto che GitBook abbia un editor markdown online che funziona molto bene e abbia un concetto simile a quello delle PR ma orientato ai non dev e quindi la barriera d’ingresso è inferiore. GitBook fa anche tante altre cose, che al momento a noi non servono. Ma, mai dire mai.

author: Mauro Servienti | posted @ mercoledì 22 febbraio 2017 13.44 | Feedback (0)

Introduzione a Semantic Versioning (SemVer)


Semantic Versioning (SemVer) è un modello di gestione del versioning finalizzato a rendere esplicito, grazie al modo in cui il numero di versione di una dipendenza evolve, quale sarà l’impatto che il fruitore deve aspettarsi installando una nuova versione della dipendenza.

Non sto qui a raccontarvi i dettagli del funzionamento, semver.org descrive tutto molte bene e in maniera sufficientemente concisa da non poter addurre la lunghezza come scusa.

TL;DR;

Per farla breve se sviluppate un libreria non potete non adottare SemVer, è una questione di buon costume e di rispetto degli altri.

Quello che volete evitare come la peste è di trovarvi in situazioni inutilmente tediose in cui siete obbligati a fare debug di codice altrui per capire perché ad un vostro cliente si è spaccato tutto.

image

La mossa del client di RavenDB di spostare delle API pubbliche in una minor change è una breaking change bella e buona che se fosse stata documentata correttamente non avrebbe causato i problemi che ha causato.

Se ci pensate diventa ovvio che il problema maggio, oltre a dover rispettare SemVer che è decisamente complesso, è che dovete separare il concetto di release commerciale da quello di release tecnica. Ne parleremo.

Avete mai pensato di usare SemVer? Se l’avete scartato quali sono stati i motivi?

author: Mauro Servienti | posted @ lunedì 20 febbraio 2017 8.31 | Feedback (0)

ServiceLocator: sei il male assoluto!


Sono sempre stato un gran fan e pure un po’ talebano di IoC e DI tant’è che già nel 2008 ne parlavo ampiamente ai Community Days con una sessione introduttiva su IoC e i vari pattern di contorno.

Ho sempre pensato che usare ServiceLocator equivalga ad andare in vacanza portandosi dietro tutta la casa, ma proprio tutti mobili compresi, come bagaglio. Neanche mia moglie che è un gran visir del bagaglio esagerato ci riesce.

Abbiamo costruito Radical con la convinzione che ServiceLocator non serva, e ci siamo riusciti senza fare pressoché nessun magheggio particolare.

Mi rendo conto che ci sono scenari, ben precisi, in cui IoC è un desiderata ma la piattoforma non aiuta, come ad esempio ASP.Net WebForms. Ma in tutti gli altri casi?

Secondo voi quali sono buone motivazioni per usare ServiceLocator?

author: Mauro Servienti | posted @ venerdì 17 febbraio 2017 19.51 | Feedback (0)

Tutti i nostri aggregati sono sbagliati - @CodemotionIT Roma, marzo 2017


L’edizione romana del workshop “Microservices development deep dive” punta a rivoluzionare il vostro modo di pensare ad un aggregato, introducendo il concetto di componente autonomo.

Una delle cose che affronteremo nel dettaglio, con anche tante demo, è proprio cosa significa modellazione di dominio quando si parla di servizi e componenti per SOA. Se siete quindi curiosi di capire perché come abbiamo immaginato gli aggregati fino ad oggi non è detto che sia il sistema migliore questo è il workshop che fa per voi :-)

Se invece è la prima volta che sentite parlare di questo workshop, qui di seguito una breve introduzione ai 4 macro argomenti che tratteremo:

Maggiori informazioni: http://rome2017.codemotionworld.com/workshop/microservices-development-deep-dive/

author: Mauro Servienti | posted @ giovedì 16 febbraio 2017 10.23 | Feedback (0)

DDD Europe, alla ricerca di nuovi stimoli.


DDDEurope2017-436

Un paio di settimane fa sono stato ad Amsterdam per DDD Europe, non per mia scelta. La spinta ad andarci è stata l’opportunità di aiutare Udi durante il workshop su Microservices.

Per uno annoiato a morte dalla tecnologia trovare nuovi stimoli non è facile e la frizione ad accettare di stare lontano 5 giorni dalla famiglia è molto alta. L’opportunità era comunque ghiotta e la scelta finale è stata restare ad Amsterdam anche per i due giorni di conferenza, oltre ai due di workshop.

Così così.

Avere a che fare con uno annoiato è molto difficile, me ne rendo perfettamente conto. Nell’insieme la conferenza è stata interessante, diciamo che se avessi dovuto pagare mi sarei lamentato.

Ripeto è il mio punto di vista, quello di uno annoiato alla ricerca di nuovi stimoli.

Elenco qui di seguito cosa ho seguito e ci metto qualche considerazione in merito.

  • Microservices workshop: gli argomenti li conosco a menadito, ho partecipato alla preparazione di tutto il materiale, la cosa per me molto interessante è stato vedere Udi in azione per due giorni;
  • Let's be open about failure and learn from it: ma anche no. Potrei parlare per ore di tutto quello che c’era di sbagliato in quella sessione senza toccare minimamente i contenuti che si faceva molta fatica a scovare;
  • The Language of Actors: noiosa e molto (troppo) base come livello, mi aspettavo molto molto di più da un super famoso;
  • To DDD or not to DDD? What to do if your domain is boring?: alla prima esperienza, brava. Argomento mainstream ma ben trattato e molto ben esposto;
  • If (domain logic) then CQRS, or Saga?: fenomenale, non tanto per i contenuti che conosco molto bene e sento quasi tutti i giorni, piuttosto per la qualità dell’esposizione e della struttura della storia che ha raccontato;
  • Modelling with strangers: è un’iniziativa molto interessante, ho partecipato a 3 sessioni, di cui 2 molto stimolanti. In una delle due Balducci ha dato sfoggio delle sue capacità;
  • DDD patterns that were not in the book: teribbbile, sembrava di leggere un GoF scritto male;
  • Design Matters: senza capo ne coda;
  • La keynote di Eric Evans: non avevo mai avuto il piacere e direi che va bene così, alcuni spunti interessanti o poco più;

In generale nutro un profondo fastidio per le sessioni senza abstract, e in questo caso mancava persino per alcune keynote, il che a mio modo di vedere è più grave.
Aggiungo: se una keynote deve essere inspiring qui ne hanno toppate 3 su 4.

Non voglio essere frainteso, quindi ripeto: è un giudizio personale, influenzato dal fatto che sono perennemente annoiato e quindi svegliarmi dal torpore è molto difficile.

author: Mauro Servienti | posted @ mercoledì 15 febbraio 2017 9.00 | Feedback (0)

Holacracy è morto, lunga vita a Holacracy.


Sabato sono stato al mini Agile Day a Vimercate, è stata una giornata molto piacevole che mi ha dato l’opportunità di conoscere persone molto interessanti. Nel mio piccolo ho avuto il piacere di raccontare come siamo organizzati in Particular.

Holacracy è morto

Nelle cosiddette chiacchiere da corridoio ho avuto l’onore e il piacere di scambiare un po’di opinioni con Angela Sanger e una delle domande che sono emerse è: non hai la sensazione che holacracy sia in una sorta di declino? (vado molto a memoria)

Non avevo una risposta sabato e non ho una risposta adesso, il weekend ha però portato una riflessione.

La sensazione è che le organizzazioni, per certi versi giustamente, siano alla ricerca della pappa pronta, del manuale con tutte le risposte, del processo ingegnerizzato già al punto giusto. Cambiare è estremamente complesso, dispendioso e faticoso e le organizzazioni sono molto brave a resistere al cambiamento.

In uno scenario di questo genere, tutto ciò che ricade sotto il cappello di holacracy, teal organization, flat organization (che nome nefasto) si presenta ad oggi come un salto nel buio. E l’osservazione dei risultati altrui spesso non è un motivo sufficiente per saltare.

Al contempo, la mia esperienza dice che un framework non è applicabile. Ogni realtà è cosa a se stante: un contesto diverso, persone diverse, obiettivi diversi. Non è minimamente pensabile applicare un set di regole che hanno funzionato per A a B; forse, ma non ne sono così certo, ci possono essere un set di linee guida che hanno funzionato con A e che si possono provare ad applicare anche B.

Manca, e io personalmente ritengo non possa esistere, una ricetta che applicata pedissequamente permetta di trasformare un’organizzazione da quello che è in qualcosa di nuovo. È interessante come il linguaggio in questo caso aiuti a confermare la mia ipotesi: trasformare un’organizzazione da quello che è in qualcosa di nuovo.

Non abbiamo una definizione, se non la parola tradizionale, per quello che sono le organizzazioni oggi e non abbiamo una definizione per identificare quello che vorremmo che fossero.

Costruire sulla sabbia

Holacracy non è morto, provocatoriamente potremmo dire che non vivrà mai. È un concetto talmente vasto e ricco di sfumature che dargli un nome è impossibile, noi internamente abbiamo scientemente deciso di evitare tutti i termini come holacracy, teal, flat, perché tendono a ricondurre ad un presunto manuale che non esiste e non può esistere.

Questo fondamentalmente significa costruire sulla sabbia. Bisogna accettare che sarà un viaggio il cui scopo non è arrivare ad una meta ma evolvere. La comprensione è il fine ultime, non la soluzione.

Da più o meno dieci anni qui a destra campeggia questo:

image

Se ci pensate anche per DDD e SOA l’obiettivo è la conoscenza. Tutto torna.

La (contro)domanda spontanea a questo punto è: valgono le stesse considerazioni per il mondo agile/scrum/xp/etc?

author: Mauro Servienti | posted @ lunedì 13 febbraio 2017 8.23 | Feedback (0)

Convention over configuration?


In Radical abbiamo un interessante problema: tutto, ma proprio tutto, è basato su Dependency Injection e Invertion of Control.

Questo in soldoni significa che concetti come DI e IoC devono essere ben chiari al nostro utente finale.

Falso.

L’assunzione è semplicemente falsa, Radical è stato disegnato con l’intenzione di nascondere la necessità di DI e IoC semplicemente perché per un uso tradizionale del framework non sono necessarie, non lo sono veramente.
Al fine di semplificare ulteriormente la barriera d’ingresso facciamo largo uso di convenzioni. Ne abbiamo parecchie, sia per la fase di boot che per quella di runtime.

Mai scelta fu più nefasta

Sarò sincero dopo 10 anni posso dire che “convention over configuration”, nelle mani di qualcuno che non ha ben chiaro cosa sta succedendo, si trasforma molto rapidamente in magia voodoo.

“Convention over configuration” comporta che:

  1. Vai a caso e ogni tanto le cose funzionano ogni tanto no
  2. Devi per forza leggere la documentazione altrimenti vai a caso e torni al punto 1
  3. Se le convenzioni sono tante, e in un sistema complesso come una LOB in WPF sono tantissime, devi conoscere a menadito la documentazione, quindi torni al punto 2 oppure ti ritrovi al punto 1

Il problema è che 1, 2 e 3 riducono la facilità d’adozione drasticamente in un sistema complesso.

Configurazioni esplicite

Le configurazioni esplicite hanno il vantaggio che se non funziona è solo perché non l’ho configurato. Attenzione che questa cosa ha un interessante impatto dal punto del framework stesso:

  1. l’utente cerca di fare una cosa
  2. la cosa non è configurata
  3. l’utente si becca una bella eccezione che gli spiega perché

Nel caso delle convenzioni il motore è obbligato a fare un po’di ipotesi e “tirare” eccezioni non è sempre così facile o ovvio, con la conseguenza che ritorniamo a rendere fondamentale la lettura della documentazione.

Quindi?

Probabilmente la risposta non c’è, al di sotto di una certa soglia di complessità la configurazione esplicita è vincente, oltre diventa talmente tediosa che è più sensato comprendere a fondo la documentazione. È ovvio che se mettete il cappello di quelli che sviluppano il framework, la risposta mica vi piace :-)

author: Mauro Servienti | posted @ venerdì 10 febbraio 2017 9.56 | Feedback (1)

Ho fatto il primo squash da command line e funziona ancora tutto


Che è un po’ come andare dagli amici e dire che finalmente sei un uomo ;-)

Scherzi a parte.

Git è uno strumento molto interessante, allo stesso tempo molto potente e la potenza si accompagna con i rischi. Git ha inoltre una caratteristica interessante: è possibile pressoché fare “undo” di tutto e quando non è possibile c’è sempre Gian Maria.

Conoscere a fondo i propri strumenti quotidiani è il metodo migliore per non farsi controllare dagli strumenti ma per controllarli; ecco che Git da linea di comando è un ottimo modo per avere piena conoscenza dello strumento e con la conoscenza controllo.

Non fatevi intimorire da Git non mangia nessuno e se vi morde chiamate Gian Maria.
Non nascondete Git dietro ad una UI che vi da controllo apparente a fronte di poca conoscenza.

Padroneggiate lo strumento, solo dopo metteteci una bella UI sopra se proprio vi serve.

author: Mauro Servienti | posted @ mercoledì 8 febbraio 2017 14.15 | Feedback (2)

Scelte tecnologiche e impatto architetturale - @CodemotionIT Roma, marzo 2017


Ho già parlato a lungo dei 4 macro argomenti che compongono il workshop “Microservices development deep dive”:

Ho anche già detto che l’edizione romana sarà molto rinnovata rispetto a quella precedente.

Quali novità?

Uno dei nuovi argomenti che tratteremo durante lo svolgimento dei 4 temi principali è che impatto hanno le scelte tecnologiche sull’architettura e viceversa. Cercheremo di capire a fondo perché scegliere una tecnologia piuttosto che un’altra. Discuteremo scelte tecnologiche estreme e a volte volutamente provocatorie con lo scopo di comprendere a fondo perché una ed una sola architettura sia una scelta spesso molto controproducente.

Maggiori informazioni: http://rome2017.codemotionworld.com/workshop/microservices-development-deep-dive/

author: Mauro Servienti | posted @ lunedì 6 febbraio 2017 11.34 | Feedback (0)

Non date nomi prematuramente, sempre per quella storia del linguaggio


Fate un favore a voi stessi, non fate la corsa al nome (parafrasando la corsa all’oro).

Torno sull’argomento importanza del linguaggio perché mi sto rendendo conto che noi tecnici siamo governati dalla frenesia del mettere in ordine, dalla necessità di trovare nel più breve tempo possibile il posto giusto per le cose. Questa stessa frenesia ci spinge, quando modelliamo, a dare molto rapidamente un nome alle cose anche se spesso non abbiamo ancora compreso a fondo.

Mai errore fu più grave

Modellare, o per dirla in termini Domain Driven Design identificare i boundary, è l’attività più difficile e fondamentale in assoluto: non farla o, forse peggio, farla male può avere conseguenze nefaste.

Una delle cose molto interessanti di avere a che fare con Services UI Composition, e in quest’ultimo periodo quasi giornalmente con Udi, è che mettete in dubbio le vostre convinzioni ad ogni piè sospinto.

Durante il processo di modellazione osservo che tendiamo a dare molto rapidamente un nome alle cose, e questo devira fondamentalmente da due cose:

  1. pensiamo spesso a come le cose sono aggregate (pensate ad una UI) per l’utente finale e traduciamo aggregate sulla UI in aggregato nel modello
  2. tendiamo a raggruppare i dati per appartenenza e non per affinità

Appartenenza e affinità

Un cliente è caratterizzato da nome, cognome, punti fragola e indirizzo di residenza. Questo è quello che la nostra tessera (la UI) dell’Esselunga ci dice, la domanda è: abbiamo quindi una classe (o aggregato) Cliente del tipo?

{
   nome: …
   cognome: …
   puntiFragola: …
   indirizzo: …
}

Una modellazione di questo tipo è figlia principalmente dell’ascoltare la cosa sbagliata.

Provate a pensare a chi modifica quei dati. I “punti fragola” hanno un ciclo di vita completamente diverso dai dati anagrafici dell’utente. Non solo probabilmente i punti fragola cambiano insieme ad altri dati, come ad esempio gli acquisti. La domanda quindi dovrebbe essere non tanto chi possiede queste caratteristiche ma piuttosto chi modifica e insieme a che cosa vengono modificate.

Per tutto il resto c’è Services UI Composition.

author: Mauro Servienti | posted @ mercoledì 1 febbraio 2017 10.04 | Feedback (0)