Contributing and Development

Relevant source files

• .claude/docs/README.md
• .github/CONTRIBUTING.md
• .github/workflows/ci.yml

This page provides a high-level guide for contributors to the helium codebase. It outlines core development workflows, rules for working with generated code, continuous integration (CI) pipelines including linting and security scanning, dependency management, and the project’s unique documentation system designed for both human developers and AI-assisted development. Detailed information about each sub-topic is available in child pages.

---

Development Workflow and Branching

The project employs a strict branching model to safeguard stable releases while enabling active development on separate branches. Contributors should:

• Target stable release branches named like v1, v2, or main only for releases [.github/CONTRIBUTING.md:114-117].
• Perform all development on corresponding development branches, e.g., develop/v2 [.github/CONTRIBUTING.md:119-122].
• Create feature branches forked from these develop/vXXX branches for any new work [.github/CONTRIBUTING.md:124-125].
• Submit pull requests against the appropriate develop/vXXX branch for review and CI validation [.github/CONTRIBUTING.md:135].
• Merges into stable branches happen post-review and CI success to produce official releases [.github/CONTRIBUTING.md:136].

Sources: .github/CONTRIBUTING.md112-138

---

Code Generation Rules

To maintain consistency and uphold compatibility with XML standards, the project relies on automated code generation. Contributors must follow these rules:

• Do not manually edit generated files. Any file ending with _gen.go is generated from source rules or spec files and will be overwritten [.github/CONTRIBUTING.md:141-143].
• When making changes that affect generated code, update both the source specification (like YAML or XML rule files) and the resulting generated files.
• The CI pipeline runs tools like stringer (for enums) to regenerate files and ensures no uncommitted changes exist post-generation [.github/workflows/ci.yml:38-41].

Common generators include:

Generator Tool	Purpose	Source or Rule File
stringer	Generates enum String() methods	Go source enum declarations
xslt3gen	Generates XSLT 3.0 instruction code	XSLT spec metadata and rules
qt3gen	Generates XPath 3.1 query test runners	W3C QT3 XML test suite files

Sources: .github/CONTRIBUTING.md140-150 .github/workflows/ci.yml38-42

---

Continuous Integration (CI) Pipelines

The helium codebase leverages GitHub Actions for a comprehensive suite of automated workflows ensuring code quality, security, and maintainability. A detailed breakdown of the workflows is available in the child page CI/CD Workflows.

Main CI Workflow (ci.yml)

Triggered on every push and pull request, this workflow performs:

1. Checkout and Cache: Clones the repo and caches Go modules in ~/go/pkg/mod for faster builds [.github/workflows/ci.yml:14-24].
2. Go Setup and Dependency Management: Installs the Go version declared in go.mod, downloads dependencies, and verifies module tidiness [.github/workflows/ci.yml:25-46].
3. Code Generation Verification: Runs stringer to regenerate parser_state_gen.go and checks for discrepancies [.github/workflows/ci.yml:38-41].
4. Testing: Executes all tests under race detector with a 20-minute timeout [.github/workflows/ci.yml:49-50].
5. Build Validation: Compiles the helium CLI tool to ensure it builds correctly [.github/workflows/ci.yml:52-54].
6. Uncommitted Changes Check: Fails the build if any generated or other files have uncommitted changes after these steps [.github/workflows/ci.yml:57-63].

Additional Workflows

• Linting: The lint.yml workflow runs golangci-lint and go vet to enforce code style and catch common issues.
• Security Scanning: The codeql.yml workflow runs GitHub CodeQL for automated static analysis and vulnerability detection.
• Fuzzing: fuzz-pr.yml and fuzz.yml manage fuzzing schedules for various components.
• Documentation Generation: autodoc.yml is responsible for generating wiki documentation.
• Release Management: release.yml handles releases using goreleaser.
• Stale Issue Management: stale.yml helps manage stale issues and pull requests.
• Dependabot: Automatically creates dependency update pull requests daily for Go modules and workflows.

Sources: .github/workflows/ci.yml1-64

---

Agent and Developer Documentation System

The project hosts a specialized documentation knowledge base in .claude/docs supporting both human developers and AI agents. This system:

• Maintains a stable index of topics to avoid token waste in large language model (LLM) queries [.claude/docs/README.md:5-6].
• Differentiates stable index documents (long-term maintained topics) from transient work product files created during active investigations [.claude/docs/README.md:11-12].
• Imposes rules on topic document creation and maintenance to avoid redundancy and encourage updates to existing docs [.claude/docs/README.md:13-14].
• Supports optimized content for AI consumption: terse, precise, and domain-specific documentation [.claude/docs/README.md:15].

This setup enables a powerful feedback loop linking natural language development requests with concrete code entities.

For detailed usage and contribution guidelines around this system, see the child page Agent and Developer Documentation System.

Sources: .github/CONTRIBUTING.md1-160 .github/workflows/ci.yml38-41 .claude/docs/README.md1-15

---

Contribution Guidelines Overview

Key contributor expectations derived from the main contributing doc:

• Contributions are welcomed but require adherence to guidelines for respect, clarity, and technical quality [.github/CONTRIBUTING.md:29-48].
• Use GitHub Issues for actionable technical problems and GitHub Discussions for usage questions or open-ended topics [.github/CONTRIBUTING.md:65-70].
• Always include runnable Go code examples, snippets, or pseudocode when reporting issues or requesting features [.github/CONTRIBUTING.md:76-88].
• Every code change must come with appropriate test cases to verify functionality and document usage [.github/CONTRIBUTING.2d:153-159].

Sources: .github/CONTRIBUTING.md1-160

---

Summary Table

Topic	Key Files / Tools	Notes
Branching & PR workflow	.github/CONTRIBUTING.md	Use develop/vXXX branches; PRs target dev
Generated Code	_gen.go files	Never manually edit; use generation tools
CI Pipeline	.github/workflows/ci.yml	Runs tests, generation, build, and validation
Security Analysis	.github/workflows/codeql.yml	Scheduled CodeQL static scans
Linting	.github/workflows/lint.yml	golangci-lint and go vet
Dependency Updates	.github/dependabot.yml	Daily dependency and workflow update PRs
Agent Documentation System	.claude/docs/	Stable index for AI/human developer docs

Sources: .github/CONTRIBUTING.md1-160 .github/workflows/ci.yml1-64 .claude/docs/README.md1-15

---

For detailed technical descriptions of workflows and the documentation system, please visit the following child pages:

• CI/CD Workflows — Comprehensive documentation of all GitHub Actions workflows including test matrices, linting, security, fuzzing, wiki generation, releases, and stale issue handling.
• Agent and Developer Documentation System — Explains the .claude/docs knowledge base architecture, maintenance rules, token optimization strategies, and AI integration points.

This completes the essential overview needed for contributors and developers engaging with the helium codebase infrastructure.