# Git workflow

## Hébergement

Dépôt sur **Bitbucket** : https://bitbucket.org/neoloop/viizia (workspace `neoloop`, slug `viizia`, **privé**).

**Auth Git HTTPS** :
- Username : `neoloop-admin` (username Bitbucket — pas l'email Atlassian, piège connu).
- Password : API token Atlassian, scopes `read:repository:bitbucket` + `write:repository:bitbucket`.
- Token de référence : `APItoken3_Neoloop_Dash_App` (token mutualisé pour tous les repos `neoloop-admin`, déjà dans le Trousseau macOS).

URL du remote :
```
https://neoloop-admin@bitbucket.org/neoloop/viizia.git
```

> Le piège « email + token » : ne **PAS** utiliser l'email Atlassian comme username — l'erreur est trompeuse (« You may not have access… »). Toujours `neoloop-admin@` dans l'URL du remote.

## Branches

Modèle **simple deux-branches** adapté au travail solo :

| Branche | Rôle |
|---|---|
| `master` | Production. Toujours déployable. Mise à jour uniquement par merge `develop → master` + tag SemVer lors des releases. |
| `develop` | Intégration **et** branche de travail courante. **Tous les commits vont directement ici.** |

**Pas de branches `feature/*`, `fix/*`, `chore/*` sur ce projet.** L'utilisateur travaille en solo et préfère un historique linéaire sur `develop` plutôt qu'une multiplicité de branches courtes. La structure du travail est portée par les **Conventional Commits** (`feat(...)`, `fix(...)`, `chore(...)`) et les tickets référencés dans les messages.

> Si l'équipe s'agrandit ultérieurement, ce choix sera à reconsidérer : un workflow multi-contributeurs nécessite alors des branches courtes pour permettre les revues de PR. Pour l'instant : **un seul flux sur `develop`**.

### Hotfix

Pour un correctif urgent en production :
1. `git checkout master`, faire le commit fix, `git push origin master`.
2. Tag : `git tag v0.X.Y && git push --tags`.
3. Reporter le fix sur `develop` : `git checkout develop && git cherry-pick <sha>` (ou simple commit si la divergence le permet).

## Commits

Format **Conventional Commits** :

```
<type>(<scope>): <sujet impératif>

<corps optionnel expliquant le pourquoi>

<refs optionnels: Fixes VIZ-12>
```

Types acceptés : `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `perf`, `style`, `build`, `ci`.

Exemples :
- `feat(import): add CSV mapping wizard`
- `fix(transaction): prevent duplicate hash collision on same-day amounts`
- `docs(specs): clarify PARTENAIRE role aggregation rules`

Règles :
- Sujet en impératif, **≤ 72 caractères**, sans point final.
- Pas de commit géant : un commit = un changement cohérent.
- Pas de `WIP` mergé.

## Pull Requests

Pas de PR au quotidien tant que le projet reste en solo (commits directs sur `develop`). Les PR ne servent que pour :
- **Releases** : PR `develop → master` à chaque montée en prod.
- **Contributions externes** futures (si l'équipe s'agrandit).

Pour ces cas :
- Titre : même convention que les commits.
- Description : ce que ça change, pourquoi, comment tester.
- CI verte obligatoire (quand elle sera en place).
- Stratégie de merge : **merge commit** sur `master` pour les releases (préserve les Conventional Commits utiles au changelog).

## Releases

- Tag SemVer : `v0.1.0`, `v0.2.0`…
- Procédure :
  1. S'assurer que `develop` est à jour et stable.
  2. Sur Bitbucket : créer une PR `develop → master`.
  3. Merger (merge commit, pas squash) → tag `v0.X.Y` sur le merge commit.
  4. `git fetch && git checkout master && git pull && git tag v0.X.Y && git push --tags`.
- Changelog automatique à partir des commits Conventional (outil : `git-cliff` ou équivalent, à mettre en place quand pertinent).

## Setup initial Bitbucket (déjà fait)

Repo créé sur Bitbucket le 2026-05-10. Procédure de premier push :

```bash
cd /Users/cguionet/_wwwroot/neoloop-viizia
git init -b master
# .gitignore créé en amont (voir section dédiée)
git add .
git commit -m "chore: initial documentation and project specs"
git remote add origin https://neoloop-admin@bitbucket.org/neoloop/viizia.git
git push -u origin master
git checkout -b develop
git push -u origin develop
```

À configurer côté Bitbucket après le premier push :
- Définir `develop` comme **branche par défaut** (UI Bitbucket → Repository settings → Default branch).
- Activer la **protection des branches** sur `master` et `develop` (Branch restrictions) : PR obligatoire, builds verts requis quand la CI sera en place.

## Auth — recovery si problème

Si le push échoue avec une erreur d'auth (changement de machine, token expiré, keychain vidé) :

```bash
# Vérifier l'URL du remote (doit contenir neoloop-admin@)
git remote -v

# Si manquant : corriger
git remote set-url origin https://neoloop-admin@bitbucket.org/neoloop/viizia.git

# Vider le keychain pour forcer la re-saisie
git credential-osxkeychain erase <<<$'protocol=https\nhost=bitbucket.org\n'

# Retenter — password = API token
git push
```

Si le token a expiré, en créer un nouveau sur https://id.atlassian.com/manage-profile/security/api-tokens (avec scopes `read:repository:bitbucket` + `write:repository:bitbucket`).

## .gitignore

`.gitignore` minimal pour la phase actuelle (uniquement de la doc) :

```
# OS
.DS_Store

# IDE
.idea/
.vscode/
*.swp
*.swo

# Env
.env.local
.env.local.php
.env.*.local

# Claude Code
.claude/settings.local.json
```

À étendre dès que Symfony sera installé :

```
# Symfony
/var/
/vendor/
/public/bundles/

# Assets
/public/assets/
/assets/vendor/
/node_modules/

# VIIZIA
/uploads/
/var/import-tmp/
docker/data/
```

## Hooks recommandés (futur)

- Pre-commit : PHP-CS-Fixer + PHPStan (rapide).
- Pre-push : tests unitaires.
- Outils : `captainhook/captainhook` ou simple script bash.