num-valid 0.3.3

# GitLab CI/CD Configuration for num-valid

This document describes the GitLab CI/CD configuration for the `num-valid` project.

## Overview

The GitLab CI/CD pipeline is configured to:

1. **Build** the project in all supported configurations
2. **Test** with all feature combinations (with/without `rug`) and build modes (Debug/Release)
3. **Analyze test coverage** using `cargo-tarpaulin`
4. **Generate badges** for pipeline status and coverage
5. **Verify security** with dependency audits

## Pipeline Structure

### Stages

1. **build** - Verifies that the code compiles
2. **test** - Runs all tests
3. **coverage** - Analyzes test coverage
4. **badges** - Updates badges and generates documentation
5. **security** - Security checks

### Build Jobs

- `build_without_rug`: Builds without the `rug` feature
- `build_with_rug`: Builds with the `rug` feature

### Test Jobs

The configuration runs tests in **all combinations**:

- `test_debug_no_rug`: Debug tests without `rug`
- `test_release_no_rug`: Release tests without `rug`
- `test_debug_with_rug`: Debug tests with `rug`
- `test_release_with_rug`: Release tests with `rug`
- `test_benchmarks`: Verifies benchmark compilation

### Additional Jobs

- `fmt_check`: Verifies formatting with `cargo fmt`
- `clippy_check`: Static analysis with `clippy`
- `doc_check`: Verifies documentation
- `coverage`: Coverage analysis with `tarpaulin`
- `security_audit`: Security audit of dependencies

## Tarpaulin Configuration

The `tarpaulin.toml` file defines 4 configurations for coverage:

```toml
[debug]
features = ""

[release]
features = ""
release = true

[rug_debug]
features = "rug"

[rug_release]
features = "rug"
release = true
```

This allows analyzing coverage separately for each combination.

## Badges

### Native GitLab Badges

These badges are automatically generated by GitLab:

```markdown
[![Pipeline Status](https://gitlab.com/YOUR_USERNAME/num-valid/badges/master/pipeline.svg)](https://gitlab.com/YOUR_USERNAME/num-valid/-/pipelines)
[![Coverage](https://gitlab.com/YOUR_USERNAME/num-valid/badges/master/coverage.svg)](https://gitlab.com/YOUR_USERNAME/num-valid/-/jobs)
```

### Badge Configuration

To enable badges, make sure that:

1. **Coverage reporting** is enabled in the GitLab project settings
2. Replace `YOUR_USERNAME` with your GitLab username in the badge URLs
3. The main branch is `master` (or modify in URLs if different)

### How to Enable Coverage Reporting

To activate coverage reporting in GitLab:

1. Go to your project on GitLab
2. Navigate to **Settings** → **CI/CD**
3. Expand the **"General pipelines"** section
4. In **"Test coverage parsing"**, enter this regex:

   ```regex
   Coverage: (\d+\.?\d*)%
   ```

5. Click **"Save changes"**

This regex matches the pattern that our pipeline prints with `tarpaulin`.

## System Requirements

### Dependencies

The pipeline automatically installs:

- **System**: `libgmp-dev`, `libmpfr-dev`, `libmpc-dev` (for `rug`)
- **Rust**: `cargo-tarpaulin` (for coverage), `cargo-audit` (for security)

### Docker Images

- **Rust jobs**: `rustlang/rust:nightly`
- **Badge jobs**: `alpine:latest`

## Cache Configuration

The cache is configured to speed up builds:

```yaml
cache:
  key:
    files:
      - Cargo.lock
      - Cargo.toml
  paths:
    - .cargo/
    - target/
```

## Special Jobs

### Nightly Tests

The `nightly_full_test` job runs comprehensive tests including benchmarks:

- Activated only on **schedule**
- Includes performance tests
- 5-minute timeout for benchmarks

### Security Audit

The `security_audit` job verifies dependencies:

- Uses `cargo-audit`
- Runs on schedule and main branches
- Non-blocking failure

## Customization

### Adding New Features

To test new features:

1. Add configurations to `tarpaulin.toml`
2. Create new test jobs in the appropriate section
3. Update coverage jobs to include the new configurations

### Modifying Coverage Criteria

The coverage badge colors are defined in `update_badges`:

- Green: ≥ 90%
- Yellow: ≥ 75%
- Red: < 75%

### Protected Branches

Critical jobs are configured to run on:

- `main`
- `master`
- `develop`

## Troubleshooting

### Build Failures

1. Verify that system dependencies are available
2. Check that the `nightly` toolchain is compatible
3. Verify `Cargo.toml` syntax

### Coverage Not Working

1. Make sure `tarpaulin.toml` is correct
2. Verify that tests pass before coverage analysis
3. Check that coverage reporting is enabled in GitLab

### Badges Not Updated

1. Verify URLs in README badges
2. Make sure the branch is correct
3. Check that coverage jobs generate reports correctly

## Monitoring

### Available Metrics

- **Pipeline success rate**: Via pipeline badge
- **Test coverage**: Via coverage badge and detailed reports
- **Build time**: In job logs
- **Artifact size**: In job pages

### Logging and Debug

- All jobs have verbose logging enabled
- Artifacts are retained for 1 week
- Coverage reports are available in HTML format

## Maintenance

### Regular Updates

- **Rust dependencies**: Update regularly in `Cargo.toml`
- **Docker images**: Monitor `rustlang/rust:nightly` updates
- **CI tools**: Update `cargo-tarpaulin`, `cargo-audit` when needed

### Performance Optimizations

- Cache is configured to maximize reuse
- Jobs are parallelized where possible
- Non-essential artifacts have short expiration