Richieste di modifica

Come il lavoro svolto nelle sessioni raggiunge il branch predefinito tramite revisione.

Una richiesta di modifica (CR) unisce un branch git a un altro. Beeuni crea una CR dal branch della sessione (head_ref) al branch predefinito del progetto (base_ref, di solito main). La riga della CR contiene metadati; l’unione, il diff e i controlli dei conflitti vengono eseguiti come vere operazioni git sul repository del progetto. Una CR è l’unico modo in cui il lavoro di una sessione arriva al branch predefinito.

Perché il lavoro passa da una CR

Una sessione viene eseguita in una sandbox sul proprio branch, che prende il nome dall’ID della sessione. La sandbox non dura per sempre, ma il branch sì: git è l’unica registrazione durevole del lavoro di una sessione. Ogni nuova sessione parte dal branch predefinito. Finché una CR non viene unita, il lavoro resta sul proprio branch, senza revisione e invisibile a tutti gli altri agenti, trigger e collaboratori. Vale per ogni modifica: codice, agenti, skill e manifest (beeuni.yaml) — nesbeeuni eccezione.

Il mandato dell’agente

Per applicare qualsiasi modifica al branch predefinito del progetto, un agente deve aprire una CR. L’agente non unisce la propria CR: la decisione spetta all’utente. Segui queste regole:

1. Esegui commit sul branch della sessione ($BEEUNI_BRANCH_NAME). Crea commit piccoli e funzionanti. Non riscrivere la cronologia né eseguire push forzati.
2. Esegui il push del branch: git push origin HEAD.
3. Apri la CR: beeuni cr open --title "..." --description "...". Nella sandbox di una sessione, --head e --session hanno come valore predefinito $BEEUNI_BRANCH_NAME e $BEEUNI_SESSION_ID. --base ha come valore predefinito il branch predefinito del progetto.
4. Comunica all’utente il numero della CR, così che possa esaminarla.
5. Fermati. Non unire la CR personalmente.

Pratiche da evitare

• Eseguire un push forzato sul branch predefinito. Viola il processo di revisione, anche se il backend lo consente.
• «È sul mio branch, prendilo tu.» Il branch della sessione scompare quando la sandbox si arresta, a meno che nel frattempo una CR non lo abbia unito.
• Inviare la modifica come file, testo incollato o archivio. Il sistema delle CR risolve già questo problema.

Modello dei dati

Le CR risiedono nella tabella change_requests.

Un indice univoco su (project_id, number) consente di fare riferimento a una CR tramite il suo numero breve anziché il suo UUID.

Ciclo di vita

open ──(merge)──▶ merged      (terminal)
open ──(close)──▶ closed ──(reopen)──▶ open

• open è lo stato iniziale.
• closed è reversibile. POST /:crId/reopen lo riporta a open.
• merged è terminale. Non è possibile riaprire o chiudere una CR unita. Apri una nuova CR sullo stato risultante dall’unione.

Beeuni rifiuta di creare una CR se il branch non contiene commit in harness sperimentaleù rispetto al branch predefinito. Di solito significa che l’agente ha eseguito il commit in locale ma non ha mai fatto il push. Esegui il push dei commit e poi crea di nuovo la CR.

Aggiornamento degli SHA

Per una CR aperta, Beeuni aggiorna head_commit_sha e base_commit_sha in base ai branch live a ogni GET. Se il repository è irraggiungibile o manca un branch, Beeuni salta l’aggiornamento e restituisce gli ultimi metadati noti della CR. Una CR unita conserva gli SHA acquisiti al momento dell’unione: Beeuni non li aggiorna harness sperimentaleù.

Meccanismi di unione

POST /v1/projects/:projectId/change-requests/:crId/merge esegue questi passaggi.

1. Beeuni legge il manifest (beeuni.yaml) da head_ref e lo convalida rispetto allo schema del manifest. Un branch senza manifest supera il controllo. Un manifest non valido restituisce 422 con code: "MANIFEST_INVALID" e interrompe l’unione.
2. Beeuni esegue il fast-forward di base_ref se head_ref è strettamente harness sperimentaleù avanti.
3. Altrimenti, Beeuni crea un commit di unione. Il messaggio predefinito è Merge CR #<n>: <title>; puoi cambiarlo con message nel corpo della richiesta. L’autore del commit è Beeuni <noreply@beeuni.com>.
4. In caso di conflitto, viene restituito 409 con l’elenco dei conflitti. Prima dell’unione, puoi controllare lo stesso elenco con GET /:crId/merge-preview.
5. In caso di esito positivo, Beeuni imposta status su merged, registra merged_at, merged_by e merge_commit_sha, e invalida la cache git del progetto.

Se la CR non è open, l’unione restituisce 409.

Anteprima dell’unione

GET /:crId/merge-preview restituisce:

API REST

Tutte le route si trovano sotto /v1/projects/:projectId/change-requests.

POST / rifiuta un head_ref che non contiene commit in harness sperimentaleù rispetto a base_ref: 422 code: "CR_HEAD_NOT_AHEAD". È l’errore che vede un agente se apre una CR prima di eseguire il push del branch.

Autorizzazioni

Le route di lettura richiedono l’accesso in lettura al progetto. Le route di scrittura richiedono l’accesso in scrittura. Ogni azione di scrittura richiede anche una capability, indicata di seguito per un token completo e per il token con ambito limitato di una sessione.

Una capability per ogni azione, sia per un token completo sia per il token con ambito limitato di una sessione. Apertura e unione sono permessi distinti: un token può aprire richieste di modifica senza poterle unire. È questo il meccanismo alla base del mandato dell’agente descritto sopra.

project.cr.open e project.cr.merge erano i nomi precedenti al passaggio per project.gitops.push e project.gitops.merge, la stessa capability con un secondo nome. Un beeuni.yaml che ne elenca ancora uno continua a funzionare (quando viene risolto, il grant viene riscritto usando la dicitura corrente), ma per ogni nuovo elemento usa il nome gitops.

Una sessione non può mai unire una richiesta di modifica che ha aperto lei stessa, indipendentemente dai permessi ricevuti. Questa regola è strutturale, non è una capability.