Skip to main content

Version Control & Baselines

NirmIQ provides two powerful version control systems that work together to give you complete change management capabilities:

  1. Internal Baselining - Built-in database versioning (always available)
  2. Git Integration - Industry-standard version control with GitHub/GitLab (optional, advanced)

Both systems run in parallel, giving you the flexibility to choose the approach that best fits your workflow.

Two Approaches to Version Control​

NirmIQ offers dual version control - you can use either system independently, or combine both for maximum power.

Internal Baselining (Built-in)​

What it is: Database-backed version control built directly into NirmIQ. No external tools required.

Best for:

  • Quick setup (works immediately, no configuration)
  • Instant UI responsiveness (all data local to NirmIQ)
  • Offline work capability
  • Teams without Git expertise
  • Regulatory compliance (21 CFR Part 11, ISO 26262, DO-178C)

How it works: Every requirement edit automatically creates a version entry. You can create named baselines to capture complete project snapshots.

Git Integration (Advanced)​

What it is: State-of-the-art Git synchronization following the Siemens Polarion model. Automatically commits requirement changes to your GitHub or GitLab repository.

Best for:

  • Developer collaboration (Git workflows engineers already know)
  • External audit trail (commits visible in GitHub/GitLab)
  • Branch-based parallel workstreams
  • Pull request workflows for formal reviews
  • Integration with CI/CD pipelines

How it works: NirmIQ automatically commits changes to your Git repository. You work in the NirmIQ UI, and changes are synced to Git in the background.

Comparison Table​

FeatureInternal BaseliningGit Integration
Setup TimeInstant (always on)5 minutes (connect repo)
User ExpertiseNone requiredBasic Git knowledge helpful
External DependenciesNoneGitHub/GitLab account
Offline Work✅ Full support⚠️ Requires periodic sync
Change GranularityPer-requirement versionsPer-requirement commits
Branching❌ Not supported✅ Full branch management
Pull Requests❌ Not supported✅ Create PRs from UI
Developer Collaboration⚠️ Within NirmIQ only✅ Full Git ecosystem
Audit Trail✅ Database records✅ Git commit history
Regulatory Compliance✅ Industry standard✅ Industry standard
UI Performance⚡ Instant queries⚡ Instant (cached)
CostIncludedIncluded

You can use both systems simultaneously:

User edits requirement in NirmIQ
    ↓
Automatic version entry created (Internal Baselining)
    ↓
Automatic Git commit created (Git Integration)
    ↓
Both systems maintain independent audit trails

Benefits:

  • Instant UI responsiveness (database queries)
  • External Git history for developers
  • Redundant audit trail for regulatory compliance
  • Best of both worlds

What is Version Control?​

Version control in NirmIQ captures and preserves snapshots of your requirements and FMEA analyses at specific points in time.

Key Concepts​

Baseline (Snapshot)

  • A named capture of your entire project state at a specific moment
  • Includes all requirements and FMEA data
  • Immutable once created - provides a permanent historical record
  • Can be compared with other baselines or current state

Version History

  • Individual requirement change tracking
  • Records each modification with change summary and reference
  • Accessible from the CR+CM (Change Request + Configuration Management) tab
  • Tracks who made changes and when

Why Use Version Control?​

Regulatory Compliance​

Version control is essential for compliance with safety-critical standards:

  • ISO 26262 (Automotive): Requires configuration management and change tracking
  • DO-178C (Aerospace): Mandates version control of requirements
  • IEC 62304 (Medical): Requires change history and traceability
  • ASPICE: Change management and baseline establishment

Project Management Benefits​

  1. Milestone Tracking: Capture project state at key milestones (reviews, releases)
  2. Change Impact Analysis: Compare baselines to understand what changed
  3. Audit Trail: Complete history of all requirement changes
  4. Rollback Capability: Reference previous versions if needed
  5. Team Collaboration: Clear record of who changed what and when
  6. Customer Communication: Demonstrate exactly what changed between releases

Real-World Use Cases​

Pre-Review Baseline

Create baseline before customer design review
→ Customer requests changes during review
→ Compare post-review state to baseline
→ Generate change report showing exactly what was modified

Release Management

Create baseline "v1.0 Release"
→ Continue development for v1.1
→ Bug found in v1.0
→ Reference v1.0 baseline to understand released state
→ Create fix based on exact v1.0 requirements

Change Request Tracking

Customer submits CR-042
→ Create baseline "Before CR-042"
→ Implement CR-042 changes
→ Create baseline "After CR-042"
→ Compare baselines to document CR-042 impact

Creating a Baseline​

A baseline captures the complete state of your project's requirements and FMEA data.

How to Create a Baseline​

  1. Open your project with requirements and/or FMEA data
  2. Click View → Create Baseline from the top menu
  3. Enter baseline information:
    • Baseline Name (required): Descriptive name for this snapshot
      • Examples: "v1.0 Release", "Pre-CDR Baseline", "CR-042 Implementation"
    • Description (optional): Additional context about this baseline
      • Examples: "State before customer design review", "Requirements frozen for release"
  4. Click Create Baseline
  5. Success message shows counts: "Baseline created! Captured 87 requirements and 12 FMEA analyses."

What Gets Captured​

When you create a baseline, NirmIQ captures:

Requirements

  • Requirement ID and custom ID
  • Full requirement text
  • Requirement type
  • Parent-child relationships
  • Version number
  • Jira links (if configured)

FMEA Analyses

  • All FMEA analyses (DFMEA, PFMEA, etc.)
  • Analysis metadata (name, description, system/subsystem/component)
  • Analysis status
  • All failure modes with:
    • Function, failure mode, effects, causes
    • Severity, Occurrence, Detection ratings
    • Calculated RPN at snapshot time (preserved even if ratings change later)
    • Current controls and recommended actions

Baseline Naming Best Practices​

Good Baseline Names:

  • ✅ "v1.0 Release" - Version-based
  • ✅ "Pre-PDR Baseline" - Milestone-based
  • ✅ "2025-11-11 Customer Freeze" - Date + event
  • ✅ "Sprint 12 End" - Sprint-based
  • ✅ "Before CR-042" - Change request

Poor Baseline Names:

  • ❌ "Baseline1" - Not descriptive
  • ❌ "test" - No context
  • ❌ "asdf" - Meaningless

Naming Convention Examples:

For releases:

  • "v1.0.0 Release"
  • "v1.1.0-beta"
  • "v2.0.0-rc1"

For milestones:

  • "Pre-PDR Baseline" (Preliminary Design Review)
  • "CDR Freeze" (Critical Design Review)
  • "Post-SRR" (System Requirements Review)

For change management:

  • "Before CR-042"
  • "CR-042 Complete"
  • "ECO-2025-003 Implementation"

Managing Baselines​

View and manage all baselines for your project.

Accessing Baseline List​

  1. Click View → Manage Baselines from the top menu
  2. The baseline management modal opens showing all project baselines

Baseline Information​

Each baseline displays:

  • Baseline Name: The name you provided
  • Created Date: When the baseline was created
  • Requirements Count: Number of requirements captured (e.g., "87 reqs")
  • FMEA Count: Number of FMEA analyses captured (e.g., "12 FMEA")
  • Description: Optional description (if provided)

Creating from Management View​

You can also create a new baseline directly from the management modal:

  1. Open View → Manage Baselines
  2. Fill in the "Create New Baseline" form at the top
  3. Click Create Baseline
  4. New baseline appears in the list below

Viewing Version History​

Track individual requirement changes over time using the version history feature.

How to View Version History​

  1. Open the CR+CM (Change Request + Configuration Management) tab
  2. Select a requirement from the list on the left
  3. The "Change History" section shows all versions of that requirement

Version History Information​

Each version entry shows:

  • Version Number: Sequential version (e.g., "1.0", "1.1", "2.0")
  • Requirement ID: The custom ID (e.g., "CR001")
  • Requirement Text: The requirement content at that version
  • Requirement Type: Type classification
  • Change Summary: Description of what changed
  • Change Reference: Optional reference (CR number, Jira ticket, etc.)
  • Modified By: User who created this version
  • Modified Date: When the version was created

Empty State​

If no version history exists for a requirement, you'll see:

No version history available for this requirement.
Versions are created when requirements are modified and explicitly versioned.

Note: Version history is created explicitly when you modify requirements and save a new version. Regular edits do not automatically create version history entries.

User Workflows​

Workflow 1: Release Baseline​

Scenario: You're preparing to release v1.0 of your product and need to capture the exact state of requirements.

Steps:

  1. Finalize requirements

    • Review all requirements in your project
    • Ensure all changes are saved
    • Verify FMEA analyses are complete

  2. Create release baseline

    • Click View → Create Baseline
    • Name: "v1.0 Release"
    • Description: "Requirements and FMEA frozen for v1.0 production release"
    • Click Create Baseline

  3. Verify baseline

    • Check success message confirms counts
    • Click View → Manage Baselines
    • Verify "v1.0 Release" appears with correct counts

  4. Continue development

    • Resume working on v1.1 features
    • v1.0 state is permanently captured in the baseline

Result: You now have a permanent record of v1.0 requirements that can be referenced later for bug fixes, customer inquiries, or regulatory audits.

Workflow 2: Customer Review​

Scenario: Customer is reviewing your requirements and will provide feedback. You want to track changes resulting from their feedback.

Steps:

  1. Capture pre-review state

    • Click View → Create Baseline
    • Name: "Pre-CDR Customer Review"
    • Description: "State before Critical Design Review with Customer XYZ on 2025-11-15"
    • Click Create Baseline

  2. Conduct review with customer

    • Present requirements to customer
    • Note their feedback and requested changes

  3. Implement changes

    • Update requirements based on customer feedback
    • Modify FMEA analyses as needed
    • Save all changes

  4. Capture post-review state

    • Click View → Create Baseline
    • Name: "Post-CDR Customer Review"
    • Description: "Incorporated customer feedback from CDR on 2025-11-15"
    • Click Create Baseline

  5. Generate change report (Future feature)

    • Compare "Pre-CDR" and "Post-CDR" baselines
    • Export list of changes for customer
    • Document what was addressed

Result: Clear documentation of customer-requested changes with before/after snapshots.

Workflow 3: Change Request Implementation​

Scenario: Customer submits CR-042 requesting additional safety requirements. You need to track the impact.

Steps:

  1. Baseline before changes

    • Click View → Create Baseline
    • Name: "Before CR-042"
    • Description: "State before implementing customer change request CR-042 (additional braking safety requirements)"
    • Click Create Baseline

  2. Review CR-042 requirements

    • Read customer change request
    • Identify affected requirements
    • Plan implementation

  3. Implement CR-042

    • Add new requirements
    • Modify existing requirements
    • Update FMEA failure modes
    • Add new safety analyses

  4. Baseline after changes

    • Click View → Create Baseline
    • Name: "After CR-042"
    • Description: "CR-042 implementation complete - added 15 new safety requirements"
    • Click Create Baseline

  5. Document impact

    • Compare baselines (future feature)
    • Note: Added 15 requirements, modified 8 requirements
    • Update project plan with actual impact

Result: Precise documentation of CR-042 scope and impact for customer billing and project tracking.

Workflow 4: Sprint Baselines​

Scenario: Agile team wants to capture requirements state at end of each sprint.

Steps:

  1. End of Sprint 10

    • Complete sprint work
    • Update all requirement statuses
    • Click View → Create Baseline
    • Name: "Sprint 10 End"
    • Description: "Requirements state at end of Sprint 10 (2025-11-01)"
    • Click Create Baseline

  2. Continue through sprints

    • Sprint 11 ends → Create "Sprint 11 End" baseline
    • Sprint 12 ends → Create "Sprint 12 End" baseline
    • etc.

  3. Review progress

    • Click View → Manage Baselines
    • See complete sprint history
    • Compare sprint baselines to show progress

Result: Historical record of requirement evolution across all sprints.

Workflow 5: Individual Requirement Versioning​

Scenario: A critical safety requirement (CR001) needs to be modified multiple times due to evolving customer needs. You want to track each change.

Steps:

  1. Initial requirement

    • Create CR001: "The braking system shall stop vehicle within 50m at 60 km/h"
    • Version: 1.0

  2. First change

    • Customer requests stricter requirement
    • Modify to: "The braking system shall stop vehicle within 40m at 60 km/h"
    • Create version entry:
      • Version Number: "1.1"
      • Change Summary: "Reduced braking distance from 50m to 40m"
      • Change Reference: "CR-028"

  3. View version history

    • Open CR+CM tab
    • Select CR001
    • See both versions listed with change summaries

  4. Second change

    • New safety analysis reveals need for even stricter requirement
    • Modify to: "The braking system shall stop vehicle within 35m at 60 km/h"
    • Create version entry:
      • Version Number: "2.0"
      • Change Summary: "Further reduced to 35m based on safety analysis"
      • Change Reference: "Internal Safety Review 2025-11-10"

  5. Audit trail

    • Version history shows complete evolution:
      • v1.0: 50m (original)
      • v1.1: 40m (CR-028)
      • v2.0: 35m (safety review)

Result: Complete audit trail for critical safety requirement showing why and when each change was made.

Comparison Features​

Future Enhancement

Baseline comparison features are coming soon! This will allow you to:

  • Compare two baselines side-by-side
  • View added, removed, and modified requirements
  • Generate change reports
  • Export comparison results

Planned Comparison Features:

  • Side-by-Side View: See two baselines next to each other
  • Change Detection: Automatically identify differences
  • Change Report: Export detailed change log
  • FMEA Comparison: Compare RPN changes between baselines
  • Visual Diff: Highlight text differences in requirements

Best Practices​

When to Create Baselines​

Create baselines at:

  • ✅ Major milestones (PDR, CDR, FDR)
  • ✅ Before customer reviews
  • ✅ After customer reviews (to document changes)
  • ✅ Release points (v1.0, v1.1, v2.0)
  • ✅ Before implementing major change requests
  • ✅ After implementing major change requests
  • ✅ Sprint/iteration boundaries (Agile teams)
  • ✅ Before major refactoring
  • ✅ Regulatory submission points
  • ✅ End of project phases

Don't create baselines:

  • ❌ After every tiny change
  • ❌ Multiple times per day
  • ❌ Before fully saving changes
  • ❌ With meaningless names like "test1"

Baseline Frequency​

Good Frequency Examples:

  • Waterfall Project: 5-10 baselines total

    • Requirements freeze
    • Design freeze
    • Each major review (PDR, CDR, FDR)
    • Release candidate
    • Final release

  • Agile Project: 1-2 baselines per sprint

    • Sprint start (optional)
    • Sprint end (recommended)

  • Customer-Driven: Before/after each customer interaction

    • Pre-review baseline
    • Post-review baseline
    • Before CR implementation
    • After CR implementation

Too Many: Creating 50+ baselines in a month makes it hard to find meaningful snapshots

Too Few: Only 1-2 baselines for a year-long project provides insufficient history

Naming Standards​

Establish a naming convention for your organization:

Template-Based:

[Type]-[Version/Name]-[Date]

Examples:
RELEASE-v1.0.0-2025-11-15
MILESTONE-CDR-2025-10-20
CR-CR042-Complete-2025-11-01
SPRINT-Sprint10-End-2025-09-30

Consistency: Use the same format across all projects in your organization

Technical Details​

What Baselines Store​

Baselines create snapshot copies of:

Requirements Table:

  • requirement_id (reference to original)
  • custom_id, text, type
  • parent_id (preserves hierarchy)
  • version_number
  • jira_link

FMEA Analyses Table:

  • analysis_id (reference to original)
  • analysis_type, name, description
  • system, subsystem, component
  • status

FMEA Failure Modes Table:

  • failure_mode_id (reference to original)
  • failure_mode_number
  • function, failure_mode, effects, causes
  • severity, occurrence, detection
  • RPN (calculated at snapshot time)
  • current_controls, recommended_actions

Data Preservation​

  • Historical References: Uses IDs without foreign key constraints
  • Permanent Record: Baselines remain even if original requirements deleted
  • RPN Capture: RPN calculated and frozen at snapshot time
  • Immutable: Once created, baseline data cannot be modified

Database Schema​

Baselines are stored in these tables:

  • version_tags - Baseline metadata
  • version_tag_requirements - Requirement snapshots
  • version_tag_fmea_analyses - FMEA analysis snapshots
  • version_tag_fmea_failure_modes - Failure mode snapshots

Version history is stored in:

  • requirement_versions - Individual requirement version history
  • fmea_versions - FMEA version history

API Integration​

Advanced Users

If you're integrating with NirmIQ programmatically, these API endpoints are available for version control.

Create Baseline​

POST /projects/{project_id}/baselines
Content-Type: application/json

{
  "tag_name": "v1.0 Release",
  "description": "Production release baseline"
}

List Baselines​

GET /projects/{project_id}/baselines

Get Baseline Details​

GET /projects/{project_id}/baselines/{baseline_id}

Compare Baselines​

GET /projects/{project_id}/baselines/{baseline1_id}/compare/{baseline2_id}

Get Requirement Version History​

GET /requirements/{requirement_id}/versions

Limitations​

Current Limitations​

  1. No Baseline Restoration: Cannot automatically restore project to baseline state (reference only)
  2. No Comparison UI: Cannot yet compare two baselines in UI (coming soon)
  3. Manual Version Creation: Requirement versions must be created explicitly (not automatic on edit)
  4. No Traceability Snapshots: Traceability links not yet captured in baselines
  5. No Branch/Merge: Linear history only (no Git-style branching)

Future Enhancements​

Planned features:

  • Baseline comparison UI with diff view
  • Automatic version creation on requirement edit
  • Baseline restoration capability
  • Traceability link snapshots
  • Visual Git-style graph in Graph tab
  • Baseline export/import
  • Baseline tagging and categorization

Comparison with Git​

How is this different from Git?​

NirmIQ Version Control:

  • ✅ Built-in, no setup required
  • ✅ Designed for requirements engineering
  • ✅ Captures RPN and calculated fields
  • ✅ User-friendly for non-developers
  • ✅ Regulatory compliance focus
  • ❌ No branching/merging
  • ❌ No distributed collaboration

Git Version Control:

  • ✅ Powerful branching/merging
  • ✅ Distributed collaboration
  • ✅ Industry standard for code
  • ❌ Requires Git knowledge
  • ❌ Not designed for requirements data
  • ❌ Doesn't understand RPN, traceability
  • ❌ JSON diffs are hard to read

Can I use both?​

Yes! NirmIQ now has native Git integration that runs automatically alongside Internal Baselining.

How it works:

  1. Internal Baselining: Every edit creates version entries (always on)
  2. Git Integration: Same edits automatically commit to your GitHub/GitLab repo (configure once)
  3. Dual audit trail: Both systems maintain independent history

Setup: See "Git Integration Setup" section below.

Git Integration Setup​

Prerequisites​

  • GitHub or GitLab account
  • A repository (public or private)
  • Personal Access Token (PAT) with repo permissions

Step 1: Generate Personal Access Token​

GitHub:

  1. Go to Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click "Generate new token (classic)"
  3. Select scopes: repo (full control of private repositories)
  4. Generate and copy token

GitLab:

  1. Go to User Settings → Access Tokens
  2. Create token with scopes: api, write_repository
  3. Generate and copy token

Step 2: Configure Git in NirmIQ​

  1. Open your project in NirmIQ
  2. Go to View menu → Git Settings
  3. Enter repository URL: https://github.com/your-org/your-repo
  4. Enter your Personal Access Token
  5. Select default branch (usually main)
  6. Click Connect Repository

Step 3: Enable Auto-Commit​

Once connected:

  • Auto-commit is enabled by default
  • Changes are batched (2-minute window)
  • Multiple edits within 2 minutes = single commit

Viewing Git History​

  • CR+CM tab → Project History → View commits
  • Click any commit to see details
  • "View in GitHub/GitLab" link opens external view

Branch Management​

  • Toolbar: Current branch dropdown
  • Switch branch: Select from dropdown
  • Create branch: Click "+" button
  • Each user can work on a different branch

Creating Pull Requests​

  1. Make changes on your feature branch
  2. Go to View → Git Settings → Merge Requests
  3. Click Create Pull Request
  4. Select source and target branches
  5. Add title and description
  6. Click Create → Opens PR in GitHub/GitLab

Troubleshooting​

Baseline Creation Fails​

Problem: "Failed to create baseline" error

Solutions:

  • Ensure you have an active project selected
  • Verify baseline name is unique (no duplicate names)
  • Check that baseline name is not empty
  • Ensure you're connected to the network
  • Try refreshing the page and trying again

Version History Empty​

Problem: "No version history available" message

Cause: Version history is not created automatically

Solution: Version history must be created explicitly when you modify requirements. This is a manual process currently. Future versions may automate this.

Can't Find Old Baseline​

Problem: Baseline I created is not showing in list

Solutions:

  • Verify you're viewing the correct project
  • Check that baseline creation succeeded (look for success message)
  • Refresh the baseline list
  • Check browser console for errors (F12 → Console)

Baseline Counts Don't Match​

Problem: Baseline shows different counts than expected

Explanation:

  • Baselines capture the exact state at snapshot time
  • If you've added/deleted requirements since then, counts will differ
  • This is expected behavior - baseline preserves historical state

Need Help?​

Last Updated: 2025-01-12