# Contributing to Beatussum's Gentoo overlay

First, thanks for wanting to contribute to my overlay.

## Table of contents

- [Table of contents](#table-of-contents)
- [How to contribute?](#how-to-contribute)
    - [General guidelines](#general-guidelines)
    - [What is specific to this overlay](#what-is-specific-to-this-overlay)
        - [Documentation files](#documentation-files)
        - [EAPI](#eapi)
        - [Ebuilds without test](#ebuilds-without-test)
        - [Extra variables](#extra-variables)
        - [Live ebuilds](#live-ebuilds)
        - [Metadata file](#metadata-file)
        - [Non-binary packages](#non-binary-packages)
        - [Package removal](#package-removal)
        - [Patch files](#patch-files)
        - [Prebuilt packages](#prebuilt-packages)
        - [Version bumps](#version-bumps)

## How to contribute?

### General guidelines

This overlay respects the same rules and coding styles as [the main Gentoo repository](https://github.com/gentoo/gentoo/).
It is recommended therefore to consult the section _Maintain ebuilds_ of [the page _Contribute to Gentoo_](https://www.gentoo.org/get-involved/contribute/); in particular, the following pages must be read

- [Basic guide to writing ebuilds](https://wiki.gentoo.org/wiki/Basic_guide_to_write_Gentoo_Ebuilds),
- and [The Gentoo Developer Manual](https://devmanual.gentoo.org/).

### What is specific to this overlay?

#### Documentation files

All documentation files should be included.
If some files need additionnal build process, they should be added only when the `doc` USE flag enabled.

#### EAPI

Only `EAPI=8` is allowed.

#### Ebuilds without test

If an ebuild does not have test, it should specify `RESTRICT="test"`.

#### Extra variables

Variable should be written using [snake case](https://en.wikipedia.org/wiki/Snake_case).

Extra variable defined as global variable should be uppercase.
If this variable _override_ an other variable among [these ones](https://devmanual.gentoo.org/ebuild-writing/variables/), it should be prefixed by `MY_`, e.g. `MY_PN="${PN^^}"`.

Local variable should be lowercase and be declared as `local`, e.g. `local my_local_variable`.

#### Live ebuilds

If you want to provide a live version of an ebuild, it is recommended to have the same ebuild for the latest version and the live one with the following pattern:

```ebuild
if [[ "${PV}" = 9999 ]]; then
    inherit git-r3
    EGIT_REPO_URI="<git URI>"
else
    SRC_URI="<src URI>"
    KEYWORDS="~amd64"
fi
```

`9999` must be replaced by the appropriate format, e.g. the live version of an ebuild with the version `19700101` should be `99999999`.

#### Metadata file

The metadata file should provide as many elements as possible, in particular, `<upstream>` should be as complete as possible.

#### Non-binary packages

If a package does not include binary files, the ebuild should include `RESTRICT="binchecks test"` and `<stabilize-allarches/>` in the metadata.xml file.

#### Package removal

If a package need to be removed, it has to be masked **15 days** before.

#### Patch files

Patch files should be created with `git format-patch`.

#### Prebuilt packages

Prebuilt packages should include in their ebuild `QA_PREBUILT` and, according to the redistribution rules, `RESTRICT="bindist mirror"`.

#### Version bumps

Versions bumps or rebumps should replace the previous version for the current `SLOT`.