Development/GitHub

GitHub Conventions

Issues, pull requests, branches, and commit messages across all duralex-* repositories.

Commit messages and PR titles

All repositories use conventional commits. Since PRs are squash-merged, the PR title becomes the commit message. The PR title format is enforced.

Format

<type>(<scope>): <Description starting with uppercase>

Scope is optional. Description starts with uppercase, does not end with punctuation.

Types

Type	When to use
feat	New feature or capability
fix	Bug fix
refactor	Code change that neither fixes a bug nor adds a feature
perf	Performance improvement
docs	Documentation only
test	Adding or updating tests
ci	CI/CD configuration
chore	Maintenance (dependencies, tooling, config)
build	Build system or packaging changes

Scopes (per repo)

Scopes are short identifiers for the area of the codebase. Each repo defines its own set.

duralex:

feat(corpus): Add source metadata discovery
fix(data): Handle missing content element in LEGI XML
refactor(annotations): Split envelope from type definitions
perf(fts): Optimize FTS query for large result sets

duralex-fr:

feat(parser): Add KALI collective agreement parser
fix(refs): Correct L/R/D prefix detection for code du travail

Breaking changes

Append ! after the scope for breaking changes:

refactor(data)!: Rename LegislationArticle fields to match URI scheme

The PR body must include a == Breaking changes == section explaining what breaks and how to migrate.

Branch naming

<type>/<issue-number>-<short-description>

Lowercase, hyphens between words. The type matches the conventional commit type.

feat/12-ecli-reference-detection
fix/34-lrd-prefix-code-travail
refactor/56-rename-article-fields
docs/78-add-packaging-conventions

Pull request template

Every duralex-* repo has a .github/pull_request_template.md:

## Summary

<!-- What does this change do and why? One to three sentences. -->

## Linked issues

<!-- Closes #123 -->

## Test plan

<!-- How was this tested? Paste test output or describe manual verification. -->

## Breaking changes

<!-- Leave empty if none. Otherwise explain what breaks and migration path. -->

PR guidelines

• Target size: under 200 lines changed. If larger, split into stacked PRs.
• One concern per PR. A bug fix does not include a refactor. A feature does not include unrelated cleanup.
• Squash-merge only. The PR title is the commit message in main.
• Link to the issue. Use Closes #N syntax so the issue auto-closes on merge.

Issue templates

Each repo has three YAML issue forms in .github/ISSUE_TEMPLATE/:

bug_report.yml

Required fields:

• Description — what happened vs. what was expected
• Reproducible example — minimal code or steps (required)
• Version info — output of pip show duralex or similar (required)
• Checklist — "I searched existing issues", "I am using the latest version"

feature_request.yml

Required fields:

• Use case — what problem does this solve? (required)
• Proposed API — how would the user call it? Code example preferred.
• Alternatives considered — what else was evaluated

config.yml

<syntaxhighlight lang="yaml"> blank_issues_enabled: false contact_links:

 - name: Questions and discussions
   url: https://github.com/duralex/duralex/discussions
   about: Ask questions and discuss ideas here

</syntaxhighlight>

Blank issues are disabled. Questions go to GitHub Discussions. Issues are for confirmed bugs and accepted features.

Labels

Namespaced prefixes for machine-parseable filtering.

Shared across all repos

type:bug
type:feature
type:refactor
type:docs
type:performance

priority:critical
priority:high
priority:medium
priority:low

status:needs-triage          (auto-applied to new issues)
status:accepted
status:blocked
status:in-progress

Per-repo area labels

duralex:

area:corpus
area:annotations
area:concepts
area:data
area:temporal

duralex-fr:

area:mcp
area:refs
area:temporal
area:courts
area:search

Changelog

Generated automatically from conventional commit messages (PR titles). Each type maps to a changelog section:

Commit type	Changelog section
feat	Added
fix	Fixed
perf	Performance
refactor!, feat!	Breaking changes
docs, test, ci, chore, build	Not included