objets_metier_rs 1.0.1

# Guide de Contribution


Merci de votre intérêt pour contribuer à **objets_metier_rs** ! 🎉

Ce guide vous aidera à contribuer efficacement au projet.

## Table des matières


- [Code de conduite](#code-de-conduite)
- [Comment contribuer](#comment-contribuer)
- [Configuration de l'environnement](#configuration-de-lenvironnement)
- [Processus de développement](#processus-de-développement)
- [Standards de code](#standards-de-code)
- [Tests](#tests)
- [Documentation](#documentation)
- [Processus de Pull Request](#processus-de-pull-request)
- [Structure du projet](#structure-du-projet)
- [Versioning et releases](#versioning-et-releases)

---

## Code de conduite


Ce projet adhère aux principes suivants :

- **Respect** : Soyez respectueux envers tous les contributeurs
- **Collaboration** : Encouragez la collaboration et l'entraide
- **Inclusivité** : Accueillez les contributions de tous horizons
- **Constructivité** : Fournissez des retours constructifs

Tout comportement inapproprié sera signalé et traité en conséquence.

---

## Comment contribuer


Il existe plusieurs façons de contribuer :

### 🐛 Signaler des bugs


Ouvrez une [Issue](https://github.com/your-repo/objets_metier_rs/issues/new) avec :
- **Titre clair** décrivant le problème
- **Description détaillée** du bug
- **Étapes pour reproduire** le problème
- **Comportement attendu** vs **comportement observé**
- **Environnement** (OS, version Rust, version Sage 100c)
- **Code minimal** reproduisant le problème

### ✨ Proposer des fonctionnalités


Ouvrez une [Discussion](https://github.com/your-repo/objets_metier_rs/discussions) ou une Issue avec :
- **Description** de la fonctionnalité proposée
- **Cas d'usage** concrets
- **API proposée** (si applicable)
- **Alternatives considérées**

### 📖 Améliorer la documentation


- Corriger des typos
- Clarifier des explications
- Ajouter des exemples
- Traduire la documentation

### 💻 Contribuer du code


Suivez le [processus de Pull Request](#processus-de-pull-request) décrit ci-dessous.

---

## Configuration de l'environnement


### Prérequis


1. **Rust 1.70+** (édition 2021)
```bash
rustup update stable

rustc --version  # Vérifier >= 1.70

```

2. **Sage 100c** installé avec `objets100c.dll`

3. **Visual Studio Build Tools** (pour Windows)
   - Télécharger depuis https://visualstudio.microsoft.com/downloads/
   - Sélectionner "Développement Desktop en C++"

4. **Git**
```bash
git --version

```

### Installation


1. **Forker** le projet sur GitHub

2. **Cloner** votre fork
```bash
git clone https://github.com/YOUR_USERNAME/objets_metier_rs.git

cd objets_metier_rs

```

3. **Ajouter le remote upstream**
```bash
git remote add upstream https://github.com/original-repo/objets_metier_rs.git

```

4. **Enregistrer la DLL Sage** (en tant qu'administrateur)
```powershell
regsvr32 "C:\Program Files\Sage\Sage 100c\objets100c.dll"
```

5. **Compiler le projet**
```bash
cargo build

```

6. **Lancer les tests**
```bash
cargo test

```

### Configuration des variables d'environnement


Pour les tests d'intégration :

```powershell
# PowerShell

$env:SAGE_DATABASE="D:\Sage\BIJOU.MAE"
$env:SAGE_USERNAME="<Administrateur>"
$env:SAGE_PASSWORD=""
```

```bash
# Bash

export SAGE_DATABASE="D:\Sage\BIJOU.MAE"
export SAGE_USERNAME="<Administrateur>"
export SAGE_PASSWORD=""
```

---

## Processus de développement


### 1. Créer une branche


```bash
# Se synchroniser avec upstream

git fetch upstream
git checkout main
git merge upstream/main

# Créer une branche feature/fix

git checkout -b feature/ma-nouvelle-fonctionnalite
# ou

git checkout -b fix/correction-bug-xyz
```

**Convention de nommage des branches :**
- `feature/description` - Nouvelles fonctionnalités
- `fix/description` - Corrections de bugs
- `docs/description` - Modifications de documentation
- `refactor/description` - Refactoring de code
- `test/description` - Ajout/modification de tests

### 2. Développer


- Écrivez du code propre et bien documenté
- Suivez les [standards de code](#standards-de-code)
- Ajoutez des tests pour votre code
- Mettez à jour la documentation si nécessaire

### 3. Tester localement


```bash
# Format du code

cargo fmt

# Linting

cargo clippy -- -D warnings

# Tests unitaires

cargo test

# Tests avec exemples

cargo test --examples

# Benchmarks (si applicable)

cargo bench
```

### 4. Committer


```bash
git add .
git commit -m "feat: ajout de la factory XYZ"
```

**Convention des messages de commit :**

Suivez [Conventional Commits](https://www.conventionalcommits.org/) :

- `feat:` - Nouvelle fonctionnalité
- `fix:` - Correction de bug
- `docs:` - Documentation uniquement
- `style:` - Formatage, point-virgules manquants, etc.
- `refactor:` - Refactoring sans changement fonctionnel
- `test:` - Ajout de tests
- `chore:` - Tâches de maintenance

**Exemples :**
```
feat: ajout de FactoryArticle pour module commercial
fix: correction fuite mémoire dans SafeDispatch
docs: amélioration du guide TRAITS_GUIDE.md
refactor: simplification de la conversion VARIANT
test: ajout tests pour FactoryTaxe
chore: mise à jour dépendances vers windows 0.52
```

### 5. Pusher


```bash
git push origin feature/ma-nouvelle-fonctionnalite
```

---

## Standards de code


### Format et style


**Rust Edition** : 2021, target 1.70+

**Formatage** : Utilisez `rustfmt`
```bash
cargo fmt
```

Configuration dans `.rustfmt.toml` (si présent) ou par défaut.

**Linting** : Utilisez `clippy`
```bash
cargo clippy -- -D warnings
```

Pas de warnings autorisés dans le code de production.

### Conventions de nommage


- **snake_case** : fonctions, variables, modules
  ```rust
  fn read_numero(numero: i32) -> SageResult<Journal>
  ```

- **PascalCase** : types, structs, enums, traits
  ```rust
  struct FactoryJournal { ... }
  trait FactoryRead<T> { ... }
  ```

- **SCREAMING_SNAKE_CASE** : constantes
  ```rust
  const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
  ```

### Imports


Groupez les imports par catégorie :

```rust
// 1. Crate interne
use crate::com::{ComInstance, SafeDispatch};
use crate::errors::{SageError, SageResult};

// 2. Crates externes
use windows::Win32::System::Com::{IDispatch, VARIANT};

// 3. Bibliothèque standard
use std::time::Duration;
```

### Gestion d'erreurs


**Toujours** utiliser `SageResult<T>` pour les fonctions pouvant échouer :

```rust
pub fn read_numero(&self, numero: i32) -> SageResult<Journal> {
    // ...
}
```

**Jamais** utiliser `.unwrap()` ou `.expect()` dans le code de bibliothèque :

```rust
// ❌ Mauvais
let value = some_result.unwrap();

// ✅ Bon
let value = some_result?;
```

**Utilisez** `#[allow(dead_code)]` pour le code futur avec commentaire :

```rust
#[allow(dead_code)]

fn future_feature() {
    // TODO: Implémentera XYZ dans v1.1.0
}
```

### Documentation


**Toutes** les APIs publiques DOIVENT avoir des doc comments :

```rust
/// Lit un journal comptable par son numéro.
///
/// # Arguments
///
/// * `numero` - Numéro unique du journal (1-based)
///
/// # Errors
///
/// Retourne une erreur si :
/// - Le journal n'existe pas
/// - La connexion COM échoue
///
/// # Examples
///
/// ```no_run
/// # use objets_metier_rs::{CptaApplication, SageResult};
/// # fn main() -> SageResult<()> {
/// let app = CptaApplication::new("...")?;
/// app.open()?;
/// 
/// let factory = app.factory_journal()?;
/// let journal = factory.read_numero(1)?;
/// println!("Code: {}", journal.jo_code()?);
/// # Ok(())
/// # }
/// ```
pub fn read_numero(&self, numero: i32) -> SageResult<Journal> {
    // Implementation
}
```

**Sections recommandées :**
- Description courte (première ligne)
- Description détaillée (si nécessaire)
- `# Arguments` - Paramètres
- `# Returns` - Valeur de retour (si non évident)
- `# Errors` - Conditions d'erreur
- `# Panics` - Conditions de panic (si applicable)
- `# Safety` - Pour code `unsafe`
- `# Examples` - Exemples d'utilisation

---

## Tests


### Tests unitaires


Chaque module doit avoir des tests :

```rust
#[cfg(test)]

mod tests {
    use super::*;

    #[test]
    fn test_parse_clsid() {
        let clsid = "309DE0FB-9FB8-4F4E-8295-CC60C60DAA33";
        let parsed = parse_clsid(clsid);
        assert!(parsed.is_ok());
    }

    #[test]
    fn test_invalid_clsid() {
        let clsid = "INVALID";
        let parsed = parse_clsid(clsid);
        assert!(parsed.is_err());
    }
}
```

### Tests d'intégration


Tests nécessitant une connexion Sage dans `tests/`:

```rust
// tests/integration_test.rs
use objets_metier_rs::{CptaApplication, SageResult};

#[test]

#[ignore] // Ignorer par défaut (nécessite Sage)

fn test_connexion_sage() -> SageResult<()> {
    let app = CptaApplication::new("309DE0FB-9FB8-4F4E-8295-CC60C60DAA33")?;
    app.set_name(std::env::var("SAGE_DATABASE")?)?;
    app.open()?;
    assert!(app.is_open()?);
    Ok(())
}
```

Exécuter avec :
```bash
cargo test -- --ignored
```

### Tests des exemples


Les exemples dans `examples/` servent aussi de tests :

```bash
cargo test --examples
```

### Couverture de tests


Visez une couverture > 80% pour le nouveau code.

Installer `tarpaulin` pour mesurer :
```bash
cargo install cargo-tarpaulin
cargo tarpaulin --out Html
```

---

## Documentation


### Documentation inline


Générer la documentation :
```bash
cargo doc --no-deps --open
```

### Documentation externe


Fichiers à mettre à jour selon les changements :

- `README.md` - Vue d'ensemble et quick start
- `CHANGELOG.md` - Historique des changements
- `docs/GUIDE_UTILISATION.md` - Guide utilisateur
- `docs/FAQ.md` - Questions fréquentes
- `docs/troubleshooting.md` - Résolution de problèmes
- `docs/TRAITS_GUIDE.md` - Documentation des traits
- `docs/PMENCODER_GUIDE.md` - Guide PMEncoder

### Exemples


Ajoutez des exemples dans `examples/` :

```rust
//! Démonstration de la nouvelle fonctionnalité XYZ
//!
//! Pour exécuter :
//! ```bash
//! $env:SAGE_DATABASE="D:\Sage\BIJOU.MAE"
//! cargo run --example xyz_demo
//! ```

use objets_metier_rs::{CptaApplication, SageResult};

fn main() -> SageResult<()> {
    // Exemple complet et fonctionnel
    Ok(())
}
```

---

## Processus de Pull Request


### 1. Vérifications pré-PR


Avant de soumettre votre PR, assurez-vous que :

```bash
# ✅ Le code compile sans warnings

cargo build --all-features

# ✅ Tous les tests passent

cargo test

# ✅ Le code est formaté

cargo fmt -- --check

# ✅ Pas de warnings clippy

cargo clippy -- -D warnings

# ✅ La documentation compile

cargo doc --no-deps
```

### 2. Créer la Pull Request


1. Allez sur votre fork GitHub
2. Cliquez sur "Compare & pull request"
3. Remplissez le template de PR :

```markdown
## Description


Brève description des changements.

## Type de changement


- [ ] Bug fix (changement non-breaking corrigeant un problème)
- [ ] Nouvelle fonctionnalité (changement non-breaking ajoutant une fonctionnalité)
- [ ] Breaking change (fix ou feature causant un changement de comportement existant)
- [ ] Documentation uniquement

## Checklist


- [ ] Mon code suit les standards du projet
- [ ] J'ai effectué une auto-review de mon code
- [ ] J'ai commenté les parties complexes
- [ ] J'ai mis à jour la documentation
- [ ] Mes changements ne génèrent pas de nouveaux warnings
- [ ] J'ai ajouté des tests couvrant mes changements
- [ ] Tous les tests passent localement
- [ ] J'ai mis à jour le CHANGELOG.md

## Tests effectués


Décrivez les tests que vous avez effectués.

## Screenshots (si applicable)


Ajoutez des screenshots si pertinent.
```

### 3. Review et ajustements


- Les mainteneurs revieweront votre PR
- Répondez aux commentaires et effectuez les modifications demandées
- Pushez les modifications sur votre branche :
  ```bash
  git add .

  git commit -m "fix: corrections suite à review"

  git push origin feature/ma-branche

  ```

### 4. Merge


Une fois approuvée, votre PR sera mergée par un mainteneur.

---

## Structure du projet


```
objets_metier_rs/
├── src/
│   ├── lib.rs                    # Point d'entrée, exports publics
│   ├── cache/                    # Système de cache
│   │   ├── mod.rs
│   │   └── factory_cache.rs
│   ├── com/                      # Couche COM bas niveau
│   │   ├── mod.rs
│   │   ├── instance.rs           # ComInstance
│   │   ├── dispatch.rs           # SafeDispatch
│   │   ├── variant.rs            # SafeVariant, conversions
│   │   ├── safe_string.rs        # Gestion BSTR
│   │   └── collection.rs         # Collections COM
│   ├── errors/                   # Gestion d'erreurs
│   │   ├── mod.rs
│   │   └── sage_error.rs         # SageError, SageResult
│   └── wrappers/                 # Wrappers métier
│       ├── mod.rs
│       ├── cpta/                 # Module Comptabilité
│       │   ├── mod.rs
│       │   ├── cpta_application_wrapper.rs
│       │   ├── loggable_wrapper.rs
│       │   ├── factories/        # 37 factories
│       │   ├── objects/          # 37 objets métier
│       │   ├── traits/           # 6 traits communs
│       │   └── process/          # PMEncoder, ErrorCollection
│       └── cial/                 # Module Commercial
│           ├── mod.rs
│           ├── cial_application_wrapper.rs
│           ├── factories/        # 38 factories
│           └── objects/          # 38 objets métier
├── examples/                     # Exemples d'utilisation
├── tests/                        # Tests d'intégration
├── benches/                      # Benchmarks
├── docs/                         # Documentation supplémentaire
├── Cargo.toml                    # Configuration
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md               # Ce fichier
└── LICENSE
```

### Où ajouter du code


- **Nouvelle factory** → `src/wrappers/{module}/factories/`
- **Nouvel objet métier** → `src/wrappers/{module}/objects/`
- **Nouveau trait** → `src/wrappers/{module}/traits/`
- **Utilitaire COM** → `src/com/`
- **Nouveau type d'erreur** → `src/errors/sage_error.rs`
- **Exemple** → `examples/`
- **Test d'intégration** → `tests/`
- **Benchmark** → `benches/`
- **Documentation** → `docs/`

---

## Versioning et releases


### Semantic Versioning


Le projet suit [SemVer](https://semver.org/) :

- **MAJOR** (v2.0.0) - Breaking changes
- **MINOR** (v1.1.0) - Nouvelles fonctionnalités (backward compatible)
- **PATCH** (v1.0.1) - Bug fixes (backward compatible)

### Processus de release


(Réservé aux mainteneurs)

1. **Mettre à jour CHANGELOG.md**
   ```markdown
   ## [1.1.0] - 2025-XX-XX
   
   ### Added
   - Nouvelle fonctionnalité X
   
   ### Fixed
   - Correction bug Y
   ```

2. **Mettre à jour version dans Cargo.toml**
   ```toml
   [package]
   version = "1.1.0"
   ```

3. **Créer un tag Git**
   ```bash
   git tag -a v1.1.0 -m "Release v1.1.0"

   git push origin v1.1.0

   ```

4. **Publier sur crates.io**
   ```bash
   cargo publish --dry-run

   cargo publish

   ```

5. **Créer une GitHub Release** avec notes du CHANGELOG

---

## Questions et support


### Besoin d'aide ?


- 📖 **Documentation** : Consultez le [README](README.md) et [docs/](docs/)
- 💬 **Discussions** : https://github.com/your-repo/objets_metier_rs/discussions
- 🐛 **Issues** : https://github.com/your-repo/objets_metier_rs/issues
- 📧 **Email** : maintainers@your-domain.com

### Ressources utiles


- [The Rust Book](https://doc.rust-lang.org/book/)
- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- [Documentation Sage 100c](docs/V12_Sage%20100cloud%20Objets%20métiers%20v1200.md)

---

## Remerciements


Merci à tous nos contributeurs ! 🎉

Votre contribution, quelle que soit sa taille, est précieuse et appréciée.

---

**Dernière mise à jour** : 2025-01-20 (v1.0.0)