einherjar/worker
2
0
Fork 0
Code Issues Pull Requests Packages Releases 1 Activity
Files
main
worker/CLA.md

91 lines
4.7 KiB
Markdown
Raw Permalink Normal View History

# 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](#1-before-you-start) 2. [Legal: CLA and Copyright](#2-legal-cla-and-copyright) 3. [Development Setup](#3-development-setup) 4. [Code Standards](#4-code-standards) 5. [Commit Messages](#5-commit-messages) 6. [Submitting a Pull Request](#6-submitting-a-pull-request) 7. [Reporting Bugs](#7-reporting-bugs) 8. [Requesting Features](#8-requesting-features) 9. [What Gets Accepted](#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](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](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 ```bash 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 ```bash 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](https://www.conventionalcommits.org/) 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`: ```bash 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](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**
2026-05-29 15:46:49 +00:00
# Contributor License Agreement
By contributing to any Einherjar repository, you agree to the terms of this Contributor License Agreement ("Agreement"). Please read it carefully before submitting your first Pull Request.
---
## 1. Definitions
| Term | Meaning |
|---|---|
| **You** | The individual or legal entity submitting a Contribution |
| **Contribution** | Any original work — source code, documentation, tests, configuration — submitted to an Einherjar repository |
| **Project** | The Einherjar framework and all repositories under `code.nochebuena.dev/einherjar/` |
| **Maintainers** | The individuals responsible for maintaining the Project |
---
## 2. You Retain Ownership
This Agreement does **not** transfer your copyright to the Maintainers. You remain the legal owner of your Contribution. What you grant here is a broad license to use it — not ownership of it.
---
## 3. Copyright License Grant
You grant the Maintainers and all recipients of the Project a **perpetual, worldwide, non-exclusive, royalty-free, irrevocable** license to:
- Reproduce, modify, and create derivative works of your Contribution
- Publicly display and perform your Contribution
- Distribute your Contribution and derivative works, in source or compiled form, under any terms
- Sublicense the above rights to third parties
- **Relicense** your Contribution under a different open-source or commercial license at the Maintainers' sole discretion
The Maintainers commit to keeping the Project available under at least one OSI-approved open-source license at all times.
---
## 4. Patent License Grant
You grant the Maintainers and all recipients of the Project a **perpetual, worldwide, non-exclusive, royalty-free, irrevocable** patent license to make, use, sell, offer for sale, import, and distribute your Contribution — limited to patent claims you own or control that are necessarily infringed by your Contribution alone, or in combination with the Project to which you submitted it.
---
## 5. Your Representations
By submitting a Contribution, you confirm that:
1. **Original work.** The Contribution is your original work, or you have the legal right to submit it under these terms.
2. **No infringement.** To your knowledge, the Contribution does not infringe any third-party intellectual property rights, including patents, copyrights, and trade secrets.
3. **Employer rights.** If your employer holds rights over intellectual property you create, you have obtained written permission to submit the Contribution on behalf of that employer, or your employer has explicitly waived such rights for contributions to open-source projects.
4. **No warranty implied.** You understand that your Contribution may or may not be included in the Project, and the Maintainers are under no obligation to use it.
---
## 6. No Support Obligation
You are not required to provide maintenance, support, or updates for your Contributions. They are accepted **"as-is"**, without any warranty of fitness for a particular purpose or correctness.
---
## 7. How to Sign
Consent is given by **posting a comment** on your Pull Request with the following exact text:
```
I have read the Einherjar Contributor License Agreement (CLA.md) and I agree to all its terms.
I confirm this Contribution is my original work. I grant the Maintainers the rights described
therein, including the right to relicense, and I retain ownership of my copyright.
This agreement covers all future Contributions I submit to any Einherjar repository under
this account.
```
**Why a comment and not a checkbox?**
PR description checkboxes can be silently toggled on and off by anyone with write access to the branch at any time. A comment creates a timestamped, author-attributed record in the PR activity log — it cannot be quietly retracted. If a comment is deleted, the deletion itself is visible in the activity log.
No handwritten or electronic signature is required beyond the comment above. A Maintainer will verify the comment before merging. PRs without the comment will not be merged.
If you are contributing on behalf of a company or organization, ensure that an authorized representative of that entity has reviewed and accepted these terms before submitting. The comment must be posted by the account that owns the Contribution.
---
## 8. Governing Terms
This Agreement is intended to be simple and broadly fair. It follows the model established by widely adopted CLAs from the Apache Software Foundation, Google, and MongoDB — granting the Project the flexibility to evolve while fully preserving your ownership of what you wrote.
If any provision of this Agreement is found unenforceable, the remaining provisions continue in full effect.
---
*For those who come after. — The Einherjar Maintainers*
Reference in New Issue Copy Permalink