GENEALOGIX

Appearance

Contributing to GENEALOGIX ​

Thank you for your interest in contributing to GENEALOGIX! Whether you're a genealogist, developer, or both, we welcome contributions of all kinds.

Table of Contents ​

How Can I Contribute? ​

For Genealogists ​

  • Improve Examples: Add real-world genealogy scenarios
  • Documentation: Clarify genealogical concepts and best practices
  • Test Cases: Contribute edge cases from your research experience
  • Use Case Reports: Share how GENEALOGIX works (or doesn't) for your needs

For Developers ​

  • Bug Fixes: Fix issues in the CLI tool or validation logic
  • New Features: Implement accepted proposals from GitHub issues
  • Performance: Optimize validation speed and memory usage
  • Tooling: Build integrations, converters, or utilities

For Everyone ​

Looking for where to start? Check issues labeled good first issue.

Development Environment Setup ​

Prerequisites ​

  • Go 1.26+ (install) — the project uses Go 1.26 in go.mod
  • Git (install)
  • Node.js — for website builds (npm install in website/) and schema validation (npm ci --prefix specification)

Dev Container ​

The easiest way to get started is with the included Dev Container:

bash
# VS Code: Install the "Dev Containers" extension, then:
# Ctrl+Shift+P → "Dev Containers: Reopen in Container"

# GitHub Codespaces: Click "Code" → "Codespaces" → "Create codespace on main"

The container includes Go, Node.js, golangci-lint, and all other tooling pre-configured.

Manual Setup ​

bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/glx.git
cd glx
git remote add upstream https://github.com/genealogix/glx.git

# Install dependencies
make install-deps

# Build and verify
make build
./bin/glx --help

# Run tests
make test

# (Optional) Install schema validation tooling
npm ci --prefix specification
make check-schemas

Install lefthook to run lint checks on staged files before each commit:

bash
make install-hooks

When Go files are staged the hook runs golangci-lint (flagging only issues introduced since HEAD, mirroring CI's only-new-issues: true); when JS/Vue files under website/.vitepress/ are staged it runs eslint on those staged files. Skip once with LEFTHOOK=0 git commit ... if needed.

Makefile Reference ​

TargetDescription
make install-depsInstall Go modules and npm packages
make install-hooksInstall lefthook pre-commit hooks (one-time)
make testRun all tests
make test-verboseRun tests with verbose output
make test-coverageRun tests with coverage report
make lintRun Go and website linters
make lint-fixRun linters with auto-fix
make fmtFormat Go and website code
make buildBuild CLI and website
make build-cliBuild just the glx binary to bin/
make check-schemasValidate JSON schema files
make check-linksValidate internal markdown links
make release-snapshotBuild cross-platform binaries locally
make cleanRemove build artifacts

Development Workflow ​

Fork and Direct-Push ​

External contributors use the fork workflow:

bash
git fetch upstream
git checkout main
git merge upstream/main
git checkout -b feat/my-feature
# ... make changes ...
git push origin feat/my-feature
# Open PR from your fork

Org members can push branches directly:

bash
git checkout main
git pull
git checkout -b feat/my-feature
# ... make changes ...
git push -u origin feat/my-feature
# Open PR

Branch Naming ​

Use conventional prefixes:

text
feat/short-description
fix/short-description
docs/short-description
chore/short-description

Commit Messages ​

Follow Conventional Commits. Valid types: feat, fix, docs, chore, refactor, test, perf, ci.

text
feat: Add GEDCOM 7.0 EXID support
fix: Handle nil map in merge
docs: Update quickstart guide

Every commit must also carry a Signed-off-by trailer — see Developer Certificate of Origin (DCO) for how to add one and what you're attesting to.

Testing ​

Prefer using the Makefile to run tests for consistency. go test directly is fine for targeted runs.

bash
make test              # Run all tests
make test-verbose      # Verbose output
make test-coverage     # Coverage report
make check-schemas     # Validate JSON schemas

Writing Tests ​

  • Unit tests for all new functions
  • Integration tests for full conversion paths
  • E2E tests for CLI commands
  • Test files live alongside source: foo.go → foo_test.go
  • GEDCOM test files: glx/testdata/gedcom/
  • Validation test fixtures: glx/testdata/valid/ and glx/testdata/invalid/

CI Checks ​

Every PR runs these checks automatically:

CheckWhat it does
Validate Specification / test-conformanceGo tests for glx/ and go-glx/ packages
Validate Specification / validate-schemasJSON schema validation
Validate Specification / validate-examplesAll example archives pass glx validate
Lint Markdown / markdownlint-cli2Structural markdown validation for specification/, docs/, root *.md
Securitygosec, govulncheck, and npm audit
lint-pr-titlePR title follows conventional commits format
dependency-reviewBlocks PRs introducing vulnerable dependencies

All checks must pass before merge.

Documentation Standards ​

Writing Style ​

  • Specification docs: Clear, precise, professional language. Define technical terms on first use.
  • User docs: Friendly, step-by-step instructions with real-world examples.

Specification documents omit the .md file extension for VitePress compatibility:

  • Good: [Person Entity](4-entity-types/person)
  • Bad: [Person Entity](4-entity-types/person.md)

Markdown Linting ​

Markdown is validated by markdownlint-cli2 in CI (see Lint Markdown above). The configuration lives in .markdownlint-cli2.jsonc at the repo root. Run it locally before pushing:

bash
npx --yes markdownlint-cli2
# auto-fix what can be fixed (whitespace, blank-line rules):
npx --yes markdownlint-cli2 --fix

Genealogical Standards ​

Submitting Changes ​

Pull Request Process ​

  1. Create an issue first for non-trivial changes
  2. Follow the PR template
  3. Ensure all CI checks pass
  4. Add tests for new features and bug fixes
  5. Update documentation if behavior changes
  6. Update CHANGELOG.md for user-facing changes (add to the unreleased section). Every entry must include an issue or PR reference — e.g. (#123), Fixes #123, Closes #123, (PR #456)

Review Process ​

  • Maintainers will review PRs within 3-5 business days
  • Address review comments promptly
  • Be open to feedback and iteration

Developer Certificate of Origin (DCO) ​

GENEALOGIX uses the Developer Certificate of Origin (DCO) 1.1 — the same lightweight attestation used by the Linux kernel, CNCF projects, and many other open-source projects. Rather than requiring a heavier Contributor License Agreement, there is no separate document to sign and no CLA bot to negotiate with. By signing off each commit, you attest that you wrote the change (or have the right to submit it) and that it can be contributed under the project's Apache 2.0 license. The DCO is an attestation of your right to contribute the code — it is not a copyright assignment. You retain copyright in your contribution. There is no automated DCO check today; sign-offs are trusted and verified manually during review.

Signing off ​

Add a Signed-off-by trailer to every commit using the -s (or --signoff) flag:

bash
git commit -s -m "feat: Add GEDCOM 7.0 EXID support"

This appends a line to the commit message using the identity from git config user.name and git config user.email:

text
Signed-off-by: Your Name <you@example.com>

Use the same name and email you use for other contributions so maintainers can reach you about your change. If user.name or user.email are wrong for this repository, set them locally before committing:

bash
git config user.name "Your Name"
git config user.email "you@example.com"

Fixing a missing sign-off ​

If you forgot -s on your most recent commit:

bash
git commit --amend --signoff --no-edit
git push --force-with-lease

For a range of commits (e.g., the last 3):

bash
git rebase --signoff HEAD~3
git push --force-with-lease

Only force-push branches you own. If others are collaborating on the branch, coordinate with them before rewriting history to avoid disrupting their work.

The DCO text ​

text
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Proposing Major Changes ​

Proposal required (via GitHub Issue) for:

  • Changes to core data model or entity types
  • New required fields or breaking changes
  • Changes to validation rules or file format

No proposal needed for:

  • Bug fixes, documentation improvements, new examples, minor clarifications

Proposal Workflow ​

  1. Create Issue: Describe the proposed change
  2. Discussion: Community reviews and comments (minimum 7 days for spec changes)
  3. Decision: Maintainers accept, reject, or request changes
  4. Implementation: After acceptance, submit a PR

Architecture Decision Records (ADRs) ​

When to write an ADR:

  • Changes to the core data model, entity types, or validation rules
  • New constraints on the library (e.g., "go-glx must never do X")
  • Choice of a major dependency, format, or protocol
  • Any decision you expect to still be referenced a year from now

For routine bug fixes, documentation improvements, and minor clarifications, no ADR is needed — a regular issue and PR are sufficient.

See docs/decisions/ for the ADR index, template, format, and proposal workflow.

AI-Generated Contributions ​

AI is welcome. Humans are accountable.

GLX is a small project with limited maintainer capacity. Every issue, PR, and comment costs human time to triage. These guidelines exist to protect that time.

All contributions must reflect genuine understanding of the GLX spec and codebase. Contributors are fully responsible for everything they submit, regardless of how it was produced. If you cannot explain your change and respond to feedback about it, do not submit it.

Autonomous Agents and Bots ​

Autonomous AI agents (OpenClaw, bounty bots, or similar) are not permitted to open issues, submit PRs, or post comments on any repository in the genealogix org. This includes agents acting on behalf of a human who is not actively supervising and reviewing each interaction.

Contributions that appear to be bot-generated will be closed without review and the account may be blocked.

PRs and Issues ​

  • Contributors are limited to 3 open PRs at a time across all genealogix repositories
  • Address all review comments on existing PRs before opening new ones

AI-Assisted Development ​

Using AI tools (Copilot, Claude, ChatGPT, etc.) as part of your workflow is fine. The bar is the same as any contribution: you understand the problem, you've tested the change, and you can engage with review feedback.

Contributors SHOULD disclose substantial AI assistance via a commit trailer:

text
Assisted-by: Claude <noreply@anthropic.com>

Co-authored-by trailers added automatically by AI coding tools are also acceptable.

Enforcement ​

Maintainers will close low-quality or bot-generated contributions without detailed explanation. Repeated violations will result in the account being blocked from the org.

We follow the Linux Foundation Generative AI Policy. Contributors must ensure AI tool terms do not conflict with the project's license.

Code of Conduct ​

We are committed to providing a welcoming and inclusive environment. Please read and follow our Code of Conduct.

Security ​

To report a vulnerability, see our Security Policy.

Building for Release ​

Releases use GoReleaser (automated in CI on tag push):

bash
# Test release build locally (requires goreleaser CLI)
make release-snapshot

Questions? ​

Thank you for contributing to GENEALOGIX!

Licensed under Apache License 2.0

Copyright © 2025-2026 Oracynth, Inc.