v1.0 Stable Release

[fank]

v1.0 Stable Release - Tracking Issue

Overview

This issue serves as the master tracking issue for releasing einvoice v1.0 - the first stable release of the Go library for reading, writing, and validating EN 16931 electronic invoices (ZUGFeRD/Factur-X format).

Goal: Deliver a stable, production-ready library with comprehensive EN 16931 core support and clear API contracts for long-term stability.

Scope: 1.0 focuses on ZUGFeRD/Factur-X (CII) format with EN 16931 core compliance. UBL format and advanced PEPPOL country-specific rules are explicitly out of scope for 1.0.

---

Release Criteria

✅ 1. Core EN 16931 Compliance

Goal: Full implementation and validation of EN 16931 v1.3.14.1 specification

• BR-1 to BR-65 (core business rules) ✅ Implemented
• BR-CO-* (calculation rules except CO-19, CO-20) ✅ Implemented
• BR-CO-19 and BR-CO-20 - Re-enable with proper implementation
  • Track: Re-enable BR-CO-19 and BR-CO-20 validation with proper implementation #44
  • Status: Currently disabled due to broken logic
  • Impact: Medium (edge case for billing period validation)
• BR-S-, BR-AE-, BR-E-, BR-Z-, BR-G-, BR-IC-, BR-IG-, BR-IP-, BR-O-* ✅ All VAT validations implemented
• BR-DEC-* (decimal precision rules) ✅ Implemented

Acceptance: All core EN 16931 validation rules pass test suite with 100% compliance

---

✅ 2. API Stability & Consistency

Goal: Clean, intuitive, backward-compatible API ready for v1 commitment

• Validation API Cleanup - Replace ValidatePEPPOL() with intelligent auto-detection

  • Track: Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46
  • Changes:
    • Make Validate() auto-detect PEPPOL vs EN 16931 based on specification identifier
    • Deprecate ValidatePEPPOL() with clear migration path
    • Rename check*.go → validate*.go for consistency
    • Rename internal check*() → validate*() functions
  • Impact: BREAKING if not handled with deprecation warnings
  • Decision Required: Implement auto-detection in 1.0 OR defer to 2.0 with deprecation warnings in 1.0?

• Exported vs Unexported Fields Review

  • Audit Invoice, InvoiceLine, Party structs for proper encapsulation
  • Ensure internal state (like violations) is not accidentally exposed
  • Add getter/setter methods where needed for future flexibility

• Error Handling Consistency

  • Review all exported functions for consistent error patterns
  • Ensure ValidationError provides clear, actionable messages
  • Document error types and when they occur

Acceptance: API review completed with no planned breaking changes post-1.0

---

📚 3. Documentation Completeness

Goal: Users can successfully adopt the library without external help

• README.md

  • Basic usage examples ✅ Present
  • Installation instructions ✅ Present
  • Clearly state UBL is NOT supported in 1.0 (move to "Limitations" section)
  • Add "Roadmap" section: UBL (1.1+), Advanced PEPPOL (1.1+), i18n (2.0+)
  • Link to pkg.go.dev documentation
  • Add CI/CD badge, test coverage badge

• pkg.go.dev Documentation

  • Package-level documentation (overview, architecture, key concepts)
  • All exported types have godoc comments
  • All exported functions have godoc with examples where helpful
  • Code examples for common workflows:
    • Parse → Validate → Write
    • Build invoice programmatically
    • Handle validation errors
    • Work with different profiles (Minimum, Basic, EN16931, Extended)

• CLAUDE.md - Update project instructions

  • Reflect any API changes from Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46
  • Update validation architecture if files are renamed
  • Add 1.0 release notes

• Migration Guide (if breaking changes)

  • Document all breaking changes since v0.x
  • Provide code migration examples
  • List deprecated functions with alternatives

Acceptance: New users can successfully parse, validate, and write invoices using only documentation

---

🧪 4. Testing & Quality Assurance

Goal: Robust test coverage ensuring reliability in production

• Test Coverage ≥ 80% ✅ Currently at 85.4%

• Edge Cases Coverage

  • Zero-value invoices (all optional fields empty)
  • Maximum field length scenarios
  • Unicode/special characters in text fields
  • Large invoices (100+ line items)
  • All profile types (Minimum → Extended)
  • Malformed XML handling (parser resilience)

• Integration Tests

  • Real-world invoice samples from test suite (e.g., ZUGFeRD test files)
  • Round-trip tests (Parse → Write → Parse → Compare)
  • Cross-profile validation (ensure Basic invoice validates as Basic)

• Performance Benchmarks (baseline for future releases)

  • Parsing performance (invoices/second)
  • Validation performance
  • Memory usage profile

• golangci-lint - Ensure clean static analysis

  • golangci-lint configured ✅ Present in go.mod
  • All critical lints passing
  • Document any intentional exceptions

Acceptance: Test suite provides confidence for production deployments

---

🔧 5. CLI Tool Stability

Goal: einvoice CLI is production-ready

• Validate Command ✅ Implemented (cmd/einvoice/validate.go)

  • Human-readable output
  • JSON output (--format json)
  • Proper exit codes (0=valid, 1=violations, 2=error)

• Info Command (optional for 1.0, recommended)

  • Track: RFC: CLI info command - invoice inspection and display #39 (RFC), RFC: CLI tool for invoice validation and inspection #13 (overall CLI RFC)
  • Provides human-readable invoice inspection
  • Decision Required: Include in 1.0 or defer to 1.1?
  • Suggestion: Defer to 1.1 to focus on core library stability

• Installation & Distribution

  • go install github.com/speedata/einvoice/cmd/einvoice@latest works
  • Binary releases via GitHub Releases (Linux, macOS, Windows)
  • Release automation (GoReleaser or similar)

• CLI Documentation

  • --help text is clear and complete
  • README has CLI usage examples
  • Man page or extended CLI docs (optional)

Acceptance: CLI can be used for production invoice validation workflows

---

🎯 6. PEPPOL BIS Billing 3.0 Support

Goal: Basic PEPPOL validation works, advanced features deferred

✅ In Scope for 1.0:

• Core PEPPOL rules (PEPPOL-EN16931-R040, R041, R042, etc.) ✅ Implemented
• ValidatePEPPOL() method ✅ Exists (to be merged into Validate() per Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46)
• PEPPOL specification identifier validation (PEPPOL-EN16931-R004)
  • Auto-detect PEPPOL invoices in Validate() (Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46)

❌ Out of Scope for 1.0 (defer to 1.1+):

• PEPPOL code list validations (CL001, CL002, etc.) - Implement PEPPOL code list and format validations #36
• PEPPOL identifier format validations (COMMON-R*) - Implement PEPPOL identifier format validations (PEPPOL-COMMON-R*) #35
• PEPPOL URN constants (Add constants and validators for PEPPOL URN identifiers #42)
• XML structure validation for PEPPOL - Add XML structure validation for PEPPOL rules #34
• Country-specific PEPPOL rules (DK, IT, NL, NO, SE) - Implement country-specific PEPPOL validation rules #33

Rationale: Core PEPPOL validation is functional. Advanced PEPPOL compliance can be enhanced iteratively in 1.1+ without breaking changes.

Acceptance: Users can validate PEPPOL invoices; advanced rules logged as known limitations

---

📦 7. Release Engineering

Goal: Smooth release process with proper versioning

• Version Tagging Strategy

  • Follow semantic versioning: v1.0.0, v1.0.1, etc.
  • Document versioning policy in CONTRIBUTING.md or README

• CHANGELOG.md

  • Create changelog with all changes since initial commits
  • Use "Keep a Changelog" format
  • Clearly mark breaking changes, deprecations, and new features

• GitHub Release

  • Draft release notes for v1.0.0
  • Include migration guide link (if applicable)
  • Attach compiled CLI binaries (multi-platform)
  • Tag release: git tag v1.0.0 && git push --tags

• Go Module Compatibility

  • Ensure go.mod has module github.com/speedata/einvoice (not /v2)
  • Verify go get github.com/speedata/einvoice@v1.0.0 works
  • Test against Go 1.24+ (documented minimum version)

• Post-Release Communication

  • Announcement in README (badge: "Stable v1.0")
  • Update pkg.go.dev (happens automatically)
  • Optional: Blog post, social media, relevant forums

Acceptance: v1.0.0 tag pushed, binaries released, documentation updated

---

Out of Scope for 1.0

The following features are explicitly deferred to future releases to ensure 1.0 quality:

1.1+ Features

• UBL Format Support - #Mentioned in README, clarify as post-1.0
• Advanced PEPPOL Validations - Code lists (Implement PEPPOL code list and format validations #36), identifier formats (Implement PEPPOL identifier format validations (PEPPOL-COMMON-R*) #35), URN constants (Add constants and validators for PEPPOL URN identifiers #42)
• CLI Info Command - Invoice inspection tool (RFC: CLI info command - invoice inspection and display #39, RFC: CLI tool for invoice validation and inspection #13)
• Country-Specific PEPPOL Rules - Denmark, Italy, Netherlands, Norway, Sweden (Implement country-specific PEPPOL validation rules #33)

2.0+ Features

• Internationalization (i18n) - Validation messages in multiple languages (Any thoughts about i18n? #30)
• Breaking API Changes - Removal of deprecated methods, major refactorings
• Alternative Serialization Formats - JSON, YAML output for invoices (if needed)

---

Pre-Release Checklist

Before tagging v1.0.0:

• All "In Scope for 1.0" items above are ✅ completed
• Test coverage ≥ 80% (currently 85.4% ✅)
• All tests pass: go test ./...
• golangci-lint clean: golangci-lint run
• Documentation reviewed by at least one other developer
• No open critical/blocker bugs
• CHANGELOG.md finalized
• README.md updated with "Stable" badge and 1.0 release info
• Migration guide published (if breaking changes exist)
• Release notes drafted

---

Decision Log

Track key decisions made during 1.0 planning:

1. UBL Support - ❌ Deferred to 1.1+
   Rationale: Focus on quality CII/ZUGFeRD support first

2. PEPPOL Advanced Rules - ❌ Deferred to 1.1+
   Rationale: Core PEPPOL validation works; code lists/formats can be added non-breaking

3. CLI Info Command - ⏸️ DECISION NEEDED
   Options: Include in 1.0 OR defer to 1.1
   Recommendation: Defer to 1.1 (focus on core library)

4. API Breaking Changes (Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46) - ⏸️ DECISION NEEDED
   Options:

   • A) Implement auto-detection in 1.0 with deprecation warnings (smooth migration)
   • B) Defer to 2.0, keep current API in 1.x (more conservative)
     Recommendation: Option A - implement with deprecation for better UX

5. i18n Support (Any thoughts about i18n? #30) - ❌ Deferred to 2.0+
   Rationale: Not critical for initial stable release, adds complexity

---

Related Issues

Blockers for 1.0:

• Re-enable BR-CO-19 and BR-CO-20 validation with proper implementation #44 - Re-enable BR-CO-19 and BR-CO-20 validation
• Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46 - Replace ValidatePEPPOL with intelligent auto-detection (API decision needed)

Nice-to-Have for 1.0:

• RFC: CLI info command - invoice inspection and display #39 - CLI info command (recommend defer to 1.1)

Post-1.0 Enhancements:

• Implement PEPPOL code list and format validations #36 - PEPPOL code list validations → 1.1
• Add constants and validators for PEPPOL URN identifiers #42 - PEPPOL URN constants → 1.1
• Implement PEPPOL identifier format validations (PEPPOL-COMMON-R*) #35 - PEPPOL identifier formats → 1.1
• Add XML structure validation for PEPPOL rules #34 - PEPPOL XML structure validation → 1.1
• Implement country-specific PEPPOL validation rules #33 - Country-specific PEPPOL rules → 1.1+
• RFC: CLI tool for invoice validation and inspection #13 - Full CLI RFC → 1.1
• Any thoughts about i18n? #30 - i18n support → 2.0+

---

Timeline Estimate

Assuming active development:

• Week 1-2:

  • Fix Re-enable BR-CO-19 and BR-CO-20 validation with proper implementation #44 (BR-CO-19/20)
  • Decide on Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46 API changes
  • Complete documentation pass

• Week 3:

  • Implement API changes (if Replace ValidatePEPPOL with intelligent auto-detection in Validate() #46 approved)
  • Add missing test coverage
  • golangci-lint cleanup

• Week 4:

  • Release engineering (binaries, CHANGELOG)
  • Final review & testing
  • Tag v1.0.0

Target Release: 4 weeks from start (adjust based on team availability)

---

Success Metrics

Post-release, 1.0 is successful if:

1. ✅ Users can parse/validate/write EN 16931 invoices without bugs
2. ✅ API remains stable for entire 1.x lifecycle (no breaking changes)
3. ✅ Documentation enables self-service adoption
4. ✅ Test coverage prevents regressions
5. ✅ Community reports no critical EN 16931 compliance gaps

---

Questions & Discussion

Please use this issue for:

• ✅ Reporting blockers or critical gaps
• ✅ Discussing "Decision Needed" items
• ✅ Proposing scope changes (with justification)
• ❌ Feature requests for post-1.0 (open separate issues)

Let's ship a solid 1.0! 🚀

[fank]

@pgundlach I just wanted something to keep track of what we may should look or focus on for 1.0, feel free to edit or remove content in this issue so we will have a clear goal of what 1.0 should or should not contain.
You can also comment on the issue so i can update it.

[pgundlach]

sounds all good to me.

I think we should try to create a simple (human readable output) for the info command before 1.0. I have one more week before going for vacation...