Editing Development/GitHub

= GitHub Conventions =

Issues, pull requests, branches, and commit messages across all <code>duralex-*</code> 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 ===

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

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

=== Types ===

{| class="wikitable"
! Type !! When to use
|-
| <code>feat</code> || New feature or capability
|-
| <code>fix</code> || Bug fix
|-
| <code>refactor</code> || Code change that neither fixes a bug nor adds a feature
|-
| <code>perf</code> || Performance improvement
|-
| <code>docs</code> || Documentation only
|-
| <code>test</code> || Adding or updating tests
|-
| <code>ci</code> || CI/CD configuration
|-
| <code>chore</code> || Maintenance (dependencies, tooling, config)
|-
| <code>build</code> || 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:'''

<pre>
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
</pre>

'''duralex-fr:'''

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

=== Breaking changes ===

Append <code>!</code> after the scope for breaking changes:

<pre>
refactor(data)!: Rename LegislationArticle fields to match URI scheme
</pre>

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

== Branch naming ==

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

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

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

== Pull request template ==

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

<pre>
## 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. -->
</pre>

=== 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 <code>main</code>.
* '''Link to the issue.''' Use <code>Closes #N</code> syntax so the issue auto-closes on merge.

== Issue templates ==

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

=== bug_report.yml ===

Required fields:

* '''Description''' — what happened vs. what was expected
* '''Reproducible example''' — minimal code or steps (required)
* '''Version info''' — output of <code>pip show duralex</code> 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 ===

<pre>
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
</pre>

=== Per-repo area labels ===

'''duralex:'''

<pre>
area:corpus
area:annotations
area:concepts
area:data
area:temporal
</pre>

'''duralex-fr:'''

<pre>
area:mcp
area:refs
area:temporal
area:courts
area:search
</pre>

== Changelog ==

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

{| class="wikitable"
! Commit type !! Changelog section
|-
| <code>feat</code> || Added
|-
| <code>fix</code> || Fixed
|-
| <code>perf</code> || Performance
|-
| <code>refactor!</code>, <code>feat!</code> || Breaking changes
|-
| <code>docs</code>, <code>test</code>, <code>ci</code>, <code>chore</code>, <code>build</code> || Not included
|}

[[Category:Development]]