# Contributing to orbintsoft-ebuild

Thanks for your interest! This is a personal Gentoo overlay, but contributions
are welcome.

## Ground rules

- **Language:** everything committed (code, comments, docs, `elog`/`einfo`
  messages, commit messages) is in **English**.
- **EAPI:** use the latest supported EAPI (currently **8**).
- **Indentation:** **tabs** in `*.ebuild` and `*.eclass` files (see
  [.editorconfig](.editorconfig)).
- **Copyright header** at the top of every ebuild/eclass:

  ```sh
  # Copyright <year> Stefano Balzarotti
  # Distributed under the terms of the GNU General Public License v3
  ```

- **Every package** must have a `metadata.xml` (GLEP 68) with a real maintainer
  and, where applicable, an `<upstream><remote-id>` entry.
- Do **not** hand-commit generated artifacts (`metadata/md5-cache/`, thin
  `Manifest` DIST entries are fine but the cache is regenerated by tooling).

## Rust packages (CRATES)

Rust ebuilds vendor their crate dependencies through a `CRATES` list so the build
runs fully offline. Generate it with **app-portage/pycargoebuild** (a dev-only
tool, kept current by Portage like the other QA tools, not by Dependabot/Renovate):

```sh
emerge -n app-portage/pycargoebuild     # one-time install
pycargoebuild path/to/upstream-source   # emits CRATES + a dependent-crate LICENSE list
```

Paste the `CRATES` block and the dependent-crate `LICENSE+=` line into the ebuild,
then add the package's own source tarball to `SRC_URI` (pycargoebuild emits only
the crate URIs, never the upstream tarball). Crates without an SPDX `license`
field — e.g. `ring` (ISC for its own code, OpenSSL for the BoringSSL-derived
parts) — trigger a warning and must have their licence added by hand. Re-run on
every version bump.

## Before opening a pull request

Run the linters via the [Makefile](Makefile) (it documents each tool and how to
install it; tooling is added incrementally — see [PLAN.md](PLAN.md)):

```sh
make lint       # pkgcheck + shellcheck + checkmake + xmllint + yamllint + actionlint
make lint-ci    # the container-free subset CI runs today (everything but pkgcheck)
```

`make lint` needs the gentoo ebuild tree for `pkgcheck`; `make lint-ci` runs
anywhere and is exactly what CI runs. Keep changes **minimal and focused** —
ideally one package per pull request.

## Reporting issues

Open a GitHub issue describing the package, your Gentoo profile, and the full
command/output (omit any personal or system-identifying data).

## License

By contributing you agree that your contributions are licensed under the
[GPL-3.0](LICENSE), consistent with the rest of the overlay.