Integrazione Git

Perché Git per la Documentazione?

Le specifiche evolvono con il codice. Ogni volta che un requisito cambia, un diagramma viene aggiornato o un piano sprint viene rivisto, quella modifica deve essere tracciata, attribuita e reversibile. Git offre esattamente questo: un sistema di versionamento maturo, distribuito e universalmente adottato dai team di sviluppo.

Usando Git per le specifiche, ogni modifica a un requisito, un diagramma o un piano sprint viene tracciata con commit, branch e tag. Il team sa chi ha modificato cosa e quando. Le specifiche e il codice possono vivere nello stesso repository, garantendo sincronizzazione perfetta: quando un developer aggiorna il codice di un modulo, può aggiornare contestualmente la specifica corrispondente nello stesso commit.

Questo approccio elimina il problema della documentazione obsoleta. Non c'è più un documento Word su una cartella condivisa che nessuno aggiorna. Le specifiche diventano living documentation: parte integrante del flusso di sviluppo, revisionate con le pull request, aggiornate con ogni feature e sempre allineate alla realtà del codice in produzione.

Why Git for Documentation?

Specs evolve with code. Every time a requirement changes, a diagram is updated, or a sprint plan is revised, that change needs to be tracked, attributed, and reversible. Git provides exactly this: a mature, distributed version control system universally adopted by development teams.

Using Git for specs, every change to a requirement, diagram, or sprint plan is tracked with commits, branches, and tags. The team knows who changed what and when. Specs and code can live in the same repository, ensuring perfect synchronization: when a developer updates a module's code, they can simultaneously update the corresponding specification in the same commit.

This approach eliminates the problem of outdated documentation. There is no more Word document on a shared folder that nobody updates. Specifications become living documentation: an integral part of the development flow, reviewed with pull requests, updated with every feature, and always aligned with the reality of the production code.

Panoramica Pannello Git

MdExplorer integra un pannello Git completo accessibile dalla sidebar laterale. Cliccando sull'icona Git, si apre un'interfaccia dedicata che permette di gestire tutte le operazioni di versionamento senza mai dover aprire un terminale o un client Git esterno.

Funzionalità principali

Il pannello Git di MdExplorer offre un set completo di funzionalità:

• Visualizzare file modificati — La lista mostra chiaramente i file divisi in staged (pronti per il commit) e unstaged (modificati ma non ancora aggiunti). Ogni file è identificato con un indicatore di stato: modificato, aggiunto, eliminato o rinominato.
• Scrivere messaggi di commit — Un campo di testo dedicato permette di scrivere messaggi di commit descrittivi. Il pannello ricorda l'ultimo messaggio usato per facilitare commit successivi sullo stesso argomento.
• Eseguire commit, push e pull — I pulsanti principali permettono di eseguire le operazioni Git più comuni con un singolo click. Il commit salva le modifiche nel repository locale, il push le invia al repository remoto e il pull scarica le ultime modifiche dal team.
• Creare e cambiare branch — L'interfaccia mostra il branch corrente e permette di crearne di nuovi o passare tra branch esistenti. Questa funzionalità è essenziale per lavorare su nuove specifiche senza interferire con quelle approvate.
• Gestire tag — Puoi creare tag per marcare versioni significative delle specifiche, visualizzare i tag esistenti e navigare tra di essi.
• Visualizzare lo storico dei commit con diff — Lo storico mostra la lista dei commit con data, autore e messaggio. Cliccando su un commit si apre il diff completo che mostra esattamente cosa è stato modificato in ogni file, con evidenziazione delle righe aggiunte e rimosse.

Git Panel Overview

MdExplorer integrates a complete Git panel accessible from the sidebar. By clicking the Git icon, a dedicated interface opens that lets you manage all version control operations without ever needing to open a terminal or an external Git client.

Main features

The MdExplorer Git panel offers a complete set of features:

• View changed files — The list clearly shows files divided into staged (ready for commit) and unstaged (modified but not yet added). Each file is identified with a status indicator: modified, added, deleted, or renamed.
• Write commit messages — A dedicated text field allows you to write descriptive commit messages. The panel remembers the last message used to facilitate consecutive commits on the same topic.
• Commit, push, and pull — The main buttons let you perform the most common Git operations with a single click. Commit saves changes to the local repository, push sends them to the remote, and pull downloads the latest changes from the team.
• Create and switch branches — The interface shows the current branch and allows creating new ones or switching between existing branches. This feature is essential for working on new specs without interfering with approved ones.
• Manage tags — You can create tags to mark significant spec versions, view existing tags, and navigate between them.
• View commit history with diff — The history shows the list of commits with date, author, and message. Clicking a commit opens the full diff showing exactly what was changed in each file, with added and removed lines highlighted.

Workflow Branching per Specifiche

Il branching è una delle funzionalità più potenti di Git e si applica perfettamente alla gestione delle specifiche. Un workflow branching ben strutturato permette al team di lavorare in parallelo su diverse specifiche, fare review e approvazioni, e mantenere un ramo principale sempre stabile e approvato.

Workflow branching: da feature branch a merge su main tramite review

Struttura dei branch consigliata

Ecco un workflow branching tipico per la gestione delle specifiche:

• main — Contiene le specifiche approvate e validate dal team. Tutto ciò che è su main rappresenta la verità corrente del progetto. Nessuno scrive direttamente su main: le modifiche arrivano sempre tramite merge da un branch di feature dopo una review.
• feature/auth-spec — Branch per le nuove specifiche in lavorazione. Ogni nuova specifica o modifica significativa viene sviluppata su un branch dedicato. Il nome del branch descrive l'argomento: feature/auth-spec, feature/payment-analysis, feature/sprint-03-plan.
• Merge tramite review — Quando la specifica è pronta, il team fa una review (tramite pull request su GitHub/GitLab oppure internamente), discute le modifiche e solo dopo l'approvazione si esegue il merge su main.

Esempio pratico

Immagina di lavorare sull'analisi del modulo di autenticazione per il tuo progetto:

1. Crei un branch feature/auth-spec dal pannello Git di MdExplorer. Questo branch parte dallo stato corrente di main e isola il tuo lavoro.
2. Scrivi le specifiche del modulo autenticazione: requisiti funzionali, flussi utente, diagrammi di sequenza, criteri di accettazione. Fai commit regolari per tracciare il progresso.
3. Condividi con il team facendo push del branch. I colleghi possono leggere le specifiche, lasciare commenti e suggerire modifiche tramite la pull request.
4. Dopo l'approvazione, esegui il merge su main. Le specifiche dell'autenticazione sono ora parte della documentazione ufficiale del progetto, allineate con il codice.

Branching Workflow for Specs

Branching is one of Git's most powerful features and it applies perfectly to specification management. A well-structured branching workflow allows the team to work in parallel on different specs, perform reviews and approvals, and keep a main branch that is always stable and approved.

Branching workflow: from feature branch to merge on main through review

Recommended branch structure

Here is a typical branching workflow for managing specifications:

• main — Contains approved and validated specs. Everything on main represents the current truth of the project. Nobody writes directly to main: changes always arrive through a merge from a feature branch after review.
• feature/auth-spec — Branch for new specs in progress. Each new spec or significant change is developed on a dedicated branch. The branch name describes the topic: feature/auth-spec, feature/payment-analysis, feature/sprint-03-plan.
• Merge through review — When the spec is ready, the team performs a review (via pull request on GitHub/GitLab or internally), discusses the changes, and only after approval is the merge to main executed.

Practical example

Imagine you are working on the authentication module analysis for your project:

1. Create a branch called feature/auth-spec from the MdExplorer Git panel. This branch starts from the current state of main and isolates your work.
2. Write the specifications for the authentication module: functional requirements, user flows, sequence diagrams, acceptance criteria. Make regular commits to track progress.
3. Share with the team by pushing the branch. Colleagues can read the specs, leave comments, and suggest changes through the pull request.
4. After approval, merge to main. The authentication specs are now part of the project's official documentation, aligned with the code.

Versionare con Tag

I tag Git sono marcatori permanenti che identificano un punto specifico nella storia del repository. Mentre i branch sono pensati per il lavoro in corso, i tag servono per marcare versioni significative e stabili delle specifiche.

Quando usare i tag

Usa i tag Git per marcare i momenti importanti nell'evoluzione delle specifiche:

• v1.0-spec — La prima versione approvata delle specifiche. Questo tag rappresenta il punto di partenza: le specifiche iniziali che il team ha concordato prima di iniziare lo sviluppo.
• v2.0-spec — Dopo una major revision delle specifiche. Quando i requisiti cambiano in modo significativo (nuovo modulo, cambio di architettura, pivot di prodotto), un nuovo tag major documenta il cambiamento.
• v1.1-spec — Per aggiornamenti minori: correzioni, chiarimenti, aggiunta di dettagli che non cambiano la sostanza dei requisiti.

Come creare un tag

I tag permettono di tornare a una versione precedente delle specifiche in qualsiasi momento. Questo è particolarmente utile quando si deve verificare cosa prevedevano le specifiche al momento dell'approvazione, oppure per confrontare la versione corrente con una precedente.

Versioning with Tags

Git tags are permanent markers that identify a specific point in the repository history. While branches are designed for work in progress, tags serve to mark significant and stable versions of specifications.

When to use tags

Use Git tags to mark important milestones in the evolution of specifications:

• v1.0-spec — The first approved version of the specs. This tag represents the starting point: the initial specs the team agreed upon before starting development.
• v2.0-spec — After a major spec revision. When requirements change significantly (new module, architecture change, product pivot), a new major tag documents the change.
• v1.1-spec — For minor updates: corrections, clarifications, added details that don't change the substance of the requirements.

How to create a tag

Tags allow going back to any previous version of specifications at any time. This is particularly useful when you need to verify what the specs stated at the time of approval, or to compare the current version with a previous one.

Esempio da Errantia

Il progetto Errantia è un caso reale di applicazione dello Spec Driven Development con MdExplorer. In questo progetto, ogni sprint ha generato commit sia nel codice che nelle specifiche, dimostrando come documentazione e implementazione possano evolversi in parallelo.

Evoluzione parallela: specifiche e codice nello stesso flusso Git

Commit paralleli: codice e specifiche

Ad esempio, il commit "BE-05: implement auth module" aggiorna sia il codice sorgente del modulo di autenticazione che il file SPRINT-01-POC.md, marcando il task come completato nella checklist dello sprint. Questo significa che guardando lo storico Git, si può vedere esattamente quando un requisito è stato implementato e quale codice corrisponde a quella specifica.

Lo storico Git racconta la storia del progetto

Lo storico Git del progetto Errantia mostra l'evoluzione parallela di codice e specifiche. Ogni sprint segue un pattern chiaro:

• Inizio sprint — Commit che aggiunge o aggiorna il file di pianificazione dello sprint (SPRINT-XX-*.md) con i task previsti, le stime e gli obiettivi.
• Durante lo sprint — Commit misti che includono sia codice che aggiornamenti alle specifiche: task completati vengono marcati, note tecniche vengono aggiunte, diagrammi vengono aggiornati per riflettere le scelte implementative.
• Fine sprint — Commit che aggiorna il file sprint con il consuntivo: task completati, task rimandati, note per lo sprint successivo, e lezioni apprese.

Questo approccio crea una tracciabilità completa tra requisiti e codice. Mesi dopo, se qualcuno chiede "perché il modulo auth funziona così?", basta consultare lo storico Git per trovare la specifica originale, le decisioni prese durante lo sprint e il codice corrispondente.

Errantia Example

The Errantia project is a real-world application of Spec Driven Development with MdExplorer. In this project, each sprint generated commits in both code and specifications, demonstrating how documentation and implementation can evolve in parallel.

Parallel evolution: specs and code in the same Git flow

Parallel commits: code and specs

For example, the commit "BE-05: implement auth module" updates both the authentication module source code and the SPRINT-01-POC.md file, marking the task as completed in the sprint checklist. This means that by looking at the Git history, you can see exactly when a requirement was implemented and which code corresponds to that specification.

Git history tells the project story

The Errantia Git history shows the parallel evolution of code and specifications. Each sprint follows a clear pattern:

• Sprint start — A commit that adds or updates the sprint planning file (SPRINT-XX-*.md) with planned tasks, estimates, and goals.
• During the sprint — Mixed commits that include both code and spec updates: completed tasks are marked, technical notes are added, diagrams are updated to reflect implementation choices.
• Sprint end — A commit that updates the sprint file with the summary: completed tasks, deferred tasks, notes for the next sprint, and lessons learned.

This approach creates complete traceability between requirements and code. Months later, if someone asks "why does the auth module work this way?", you just need to check the Git history to find the original specification, the decisions made during the sprint, and the corresponding code.