core/CONTRIBUTING.md

Contributing to Einherjar

Thank you for your interest in contributing to Einherjar. This document explains everything you need to know before sending your first Pull Request.

Einherjar is developed and maintained by NOCHEBUENADEV, the trade name of its founder operating as a Persona Física con Actividad Empresarial (PFAE) under Mexican law. Contributions are welcome and valued — but they are accepted under the terms described here, so please read this document fully before you begin.

---

Table of Contents

1. Before You Start
2. Legal: CLA and Copyright
3. Development Setup
4. Code Standards
5. Commit Messages
6. Submitting a Pull Request
7. Reporting Bugs
8. Requesting Features
9. What Gets Accepted

---

1. Before You Start

Open an issue first for anything non-trivial.

Before you write a line of code, open an issue describing what you want to change and why. This protects your time: a change that seems straightforward may conflict with a planned refactor, an architectural decision, or the project's direction. Getting alignment before coding means your PR will not be rejected for reasons unrelated to its quality.

Exceptions where you can skip the issue:

• Typo or documentation-only fix
• Test coverage improvement for existing behavior
• Trivially obvious bug with a clear, contained fix

Do not submit a PR that changes the public API of any module without prior discussion. Every Einherjar module has a stability contract. Breaking changes require a major version bump and coordinated updates across dependent modules.

---

2. Legal: CLA and Copyright

Contributor License Agreement

Before your first PR can be merged, you must sign the Contributor License Agreement by posting a specific comment on your Pull Request. The required comment text and full instructions are in CLA.md.

Checkboxes in PR descriptions are not used for CLA consent — they can be silently toggled by anyone. A comment is a timestamped, author-attributed record.

Copyright

All original code in Einherjar is copyright NOCHEBUENADEV. NOCHEBUENADEV is the registered trade name of its founder, a natural person operating under the Mexican Persona Física con Actividad Empresarial (PFAE) regime.

When you contribute, you retain ownership of what you wrote. By signing the CLA you grant NOCHEBUENADEV a perpetual, irrevocable, worldwide license to use, modify, sublicense, and redistribute your Contribution — including the right to relicense it. See CLA.md for the full terms.

License

Einherjar is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). Your Contributions will be distributed under the same license unless the Maintainers exercise their relicensing rights under the CLA.

---

3. Development Setup

Einherjar uses a Go workspace (go.work) that spans all modules. You do not need to go get anything — local replacements are wired automatically.

Prerequisites

• Go 1.26+
• Git

Clone and initialize

git clone https://code.nochebuena.dev/einherjar/<module-name>
cd <module-name>

# If working across multiple modules, clone the workspace root instead
# and all modules will resolve from disk via go.work.

Verify your setup

go build ./...   # must compile clean
go vet ./...     # no warnings
go test ./...    # all tests pass
gofmt -l .       # no output (no unformatted files)

All four commands must produce clean output before a PR will be reviewed.

---

4. Code Standards

These are non-negotiable. Every PR is checked against them.

One exported type per file (CT-6)

Each non-test .go file may contain at most one exported TypeSpec (type, struct, or interface declaration). Unexported helpers, constants, and functions may coexist in the same file. _test.go files are exempt.

This rule exists to keep the codebase navigable: a developer who knows the type name can immediately predict the file name.

provider.go         ← type Provider interface { ... }    ✓ one exported type
component.go        ← type Component interface { ... }   ✓ one exported type
new.go              ← func New(...) + unexported impl     ✓ zero exported types

Formatting

All code must be formatted with gofmt. No exceptions. If gofmt -l . produces output, the PR will not be merged.

Do not configure your editor to use goimports as a replacement — it may add import groups that diverge from the project style. Use gofmt + manual import management.

Naming conventions

• Follow standard Go naming: CamelCase for exported, camelCase for unexported.
• Interfaces that represent a capability are named with an agent noun: Provider, Sender, Checkable.
• Interfaces that represent a full component are named Component.
• Config structs are named Config. One config struct per module root.
• Constructors are named New (main) or NewXxx (adapters and variants).

Error handling

• Use core/xerrors for all errors returned from public API. Never return raw errors.New or fmt.Errorf from exported functions.
• Error codes must map to the gRPC canonical set defined in xerrors. If you need a new code, open an issue first.
• Do not swallow errors silently. Log at the appropriate level or return them.

No comments unless necessary

Do not add comments that restate what the code already says. Only add a comment when the why is non-obvious: a hidden constraint, a subtle invariant, a workaround for a known upstream bug. If removing the comment would not confuse a future reader, do not write it.

Dependencies

Do not add new external dependencies without opening an issue and getting explicit approval first. Einherjar modules are deliberately lean. Every new dependency increases the blast radius for downstream consumers.

---

5. Commit Messages

Follow the Conventional Commits specification:

<type>(<scope>): <short description>

[optional body]

Type	When to use
feat	New exported function, type, or behavior
fix	Bug fix in existing behavior
docs	Documentation only
test	Tests only, no production code change
refactor	Code restructure with no behavior change
chore	Build system, CI, dependency updates

Scope is the module name without the einherjar/ prefix: core, web, db-postgres, cache-valkey, etc.

Examples:

feat(cache-valkey): add IncrWithTTL for atomic fixed-window counters
fix(db-postgres): handle pgconn deadline exceeded as ErrDeadlineExceeded
docs(web): document rate limiter fail-open behavior

Keep the subject line under 72 characters. Write in the imperative mood ("add", "fix", "remove" — not "added", "fixes", "removed").

---

6. Submitting a Pull Request

1. Open an issue first (see §1) unless the change is trivial.
2. Fork the repository and create a branch from main:

   git checkout -b feat/your-feature-name
   

3. Make your changes following the standards in §4.
4. Ensure all verification commands pass (§3).
5. Open the PR against main using the provided PR template.
6. Post the CLA comment on the PR before requesting review (see §2 and CLA.md).
7. Respond to review feedback. Keep the review cycle short by addressing all comments before re-requesting review.

Branch naming

Prefix	Use for
feat/	New features
fix/	Bug fixes
docs/	Documentation changes
test/	Test additions or improvements
refactor/	Refactors without behavior change

PR size

Keep PRs focused. A PR that does one thing is easier to review, faster to merge, and safer to revert if needed. If your change naturally spans multiple concerns, split it into multiple PRs.

---

7. Reporting Bugs

Open an issue with the following information:

• Module affected (einherjar/db-postgres, einherjar/web, etc.)
• Go version (go version)
• Minimal reproduction — the smallest code snippet that demonstrates the problem
• Expected behavior vs actual behavior
• Error output if applicable (sanitize any credentials or sensitive data)

Do not open a PR to fix a bug without first opening an issue. The bug may be intentional behavior, already fixed on main, or caused by something outside the module.

---

8. Requesting Features

Open an issue with:

• What you want to add and why it belongs in the framework (not in application code)
• Which module it affects, or whether it requires a new module
• API sketch — what the interface, function signature, or config field would look like
• Alternative approaches you considered

Feature requests that add a new external dependency, change a public interface, or cross module boundaries require longer discussion before approval.

---

9. What Gets Accepted

Einherjar is a focused framework. It covers a specific, well-defined set of infrastructure concerns. Contributions that fall outside that scope — however well-written — will not be merged.

What fits:

• Bug fixes in existing behavior
• Performance improvements with benchmarks
• Missing error mappings for existing drivers
• Documentation improvements and example corrections
• Test coverage for untested edge cases

What does not fit without prior architectural agreement:

• New modules (open an issue first)
• New external dependencies
• Changes to public interfaces in any module
• Features that belong in application code rather than the framework

If you are unsure, open an issue and ask. It costs nothing and saves everyone time.

---

Einherjar was built for those who come after. Contributions that hold to that standard — clear, documented, tested, designed for the developer who was never in the room — are always welcome.

— NOCHEBUENADEV