> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wethehivers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & changelog

> Politique de versioning, breaking changes et historique des versions

# Versioning

THE HIVE suit un versioning **par préfixe d'URL**. La version courante est `v1` — tous les endpoints sont préfixés par `/v1/api/`.

## Politique

```mermaid theme={null}
flowchart LR
    V1[/v1/api] -.->|breaking change| V2[/v2/api]
    V1 -.->|6 mois overlap| V1E[Deprecated]
    V1E -.->|6 mois| V1EOL[End of life]
    V2 --> STABLE[Stable]
```

| Phase           | Durée                              | Statut                               |
| --------------- | ---------------------------------- | ------------------------------------ |
| **Current**     | Jusqu'à la prochaine version       | Activement développée                |
| **Deprecated**  | 6 mois après sortie de la suivante | Encore servie + header `Deprecation` |
| **End of life** | Après les 6 mois                   | Retour `410 Gone`                    |

<Info>
  Une version reste servie pendant **minimum 12 mois** après sa sortie.
</Info>

## Qu'est-ce qu'un breaking change ?

| Change                                       | Breaking ? |
| -------------------------------------------- | ---------- |
| Ajout d'un endpoint                          | Non        |
| Ajout d'un champ optionnel à une réponse     | Non        |
| Ajout d'un champ optionnel à une requête     | Non        |
| Retrait d'un endpoint                        | **Oui**    |
| Retrait d'un champ de réponse                | **Oui**    |
| Renommage d'un champ                         | **Oui**    |
| Changement de type d'un champ                | **Oui**    |
| Changement de comportement silencieux        | **Oui**    |
| Rendre obligatoire un champ optionnel        | **Oui**    |
| Ajout d'une règle de validation plus stricte | **Oui**    |
| Changement du format de date                 | **Oui**    |

## Headers de dépréciation

Lorsque v2 est en place, v1 retournera :

```http theme={null}
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 18 Oct 2026 23:59:59 GMT
Link: <https://docs.wethehivers.com/migration-v2>; rel="deprecation"
```

## Changelog

### v1.0 — 2026-04-18

**Premier release public.**

* 172 endpoints exposés
* 9 modules : auth, candidats, recruteurs, offres, candidatures, vivier, fichiers, admin, référence
* OpenAPI 3.0 spec publique
* Authentification JWT (access + refresh)
* Stockage Cloudflare R2
* Recherche plein-texte PostgreSQL (`tsvector`)
* Intégration Cloudflare + DDoS protection

### v0.9 — 2026-03-15 (interne)

* Migration `legacy-api` → `/v1/api`
* Ajout blacklist JWT Redis
* CORS restreint par domaine

### v0.8 — 2026-02-01 (interne)

* Refactor Flyway (baseline migration)
* Ajout candidature withdraw / delete
* Upload fichiers batch

***

## Déprécations actives

Aucune déprécation active à ce jour.

## Notifications

Les breaking changes majeurs sont annoncés :

* **3 mois avant** sur `https://status.wethehivers.com`
* **Email** aux recruteurs ACTIVE et admins
* **Header `Deprecation`** à partir de la sortie de la version suivante

## Tag SemVer

En interne le backend suit SemVer (`MAJOR.MINOR.PATCH`) mais **seul le MAJOR** impacte le préfixe d'URL.

```mermaid theme={null}
flowchart LR
    M1[1.x.x] -->|patch| M1P[1.0.1]
    M1 -->|minor| M1M[1.1.0]
    M1 -->|major| M2[2.0.0]
    M2 -->|URL| V2U[/v2/api]
```