172 lines
4.8 KiB
Markdown
Executable File
172 lines
4.8 KiB
Markdown
Executable File
# Contributing to profile
|
|
|
|
Thank you for your interest in contributing. This document explains how to get
|
|
set up, what the conventions are, and how to submit work.
|
|
|
|
---
|
|
|
|
## 1. Before you start
|
|
|
|
- Check the [to-do list](./todo.md) to see if your idea is already planned.
|
|
- Check the [issue tracker](https://git.geoffray-levasseur.org/fatalerrors/profile/issues)
|
|
to avoid duplicate work.
|
|
- For significant changes, open an issue or contact the maintainer before
|
|
writing code — alignment on design saves everyone time.
|
|
|
|
---
|
|
|
|
## 2. Getting the source
|
|
|
|
A Git clone is mandatory for contributions:
|
|
|
|
```bash
|
|
git clone https://git.geoffray-levasseur.org/fatalerrors/profile.git
|
|
cd profile
|
|
```
|
|
|
|
Always work from the **latest commit on `master`** (or the branch you intend
|
|
to target). Stale forks cause avoidable merge conflicts.
|
|
|
|
---
|
|
|
|
## 3. Development environment
|
|
|
|
| Requirement | Minimum version | Notes |
|
|
|---|---|---|
|
|
| Bash | 4.3 | Namerefs (`local -n`) required |
|
|
| shellcheck | any recent | Run before every commit |
|
|
| git | any | For contributing patches |
|
|
| bats-core | 1.x | Optional — for running the test suite |
|
|
|
|
Install shellcheck:
|
|
```bash
|
|
# Debian / Ubuntu
|
|
apt-get install shellcheck
|
|
|
|
# Fedora / RHEL
|
|
dnf install ShellCheck
|
|
|
|
# macOS
|
|
brew install shellcheck
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Code style
|
|
|
|
### General rules
|
|
- **Bash only** — no external interpreters in core modules. Python or Perl is
|
|
acceptable for completely self-contained, optional utilities that have no
|
|
dependencies beyond a minimal Debian or CentOS installation.
|
|
- **4-space indentation** — no tabs.
|
|
- **`[[ … ]]`** for all conditionals — not `[ … ]`.
|
|
- **`(( … ))`** for arithmetic — not `$(( … ))` in conditionals.
|
|
- **`local`** for all function-internal variables — avoid polluting the
|
|
environment.
|
|
- **`printf`** instead of `echo` wherever the format matters.
|
|
- **Never `eval`** — use namerefs (`local -n`), `${!varname}` indirection, or
|
|
`declare -g` instead.
|
|
- **No hardcoded defaults** — wire every configurable value through
|
|
`${VAR:-default}` and document the key in `profile.conf` and `README.md §4`.
|
|
|
|
### Function conventions
|
|
- Public functions **must** be exported: `export -f funcname`.
|
|
- Every public function **must** support `-h` / `--help` and print usage to
|
|
stdout, returning 0.
|
|
- Use `getopt` (not `getopts`) for option parsing — it handles long options and
|
|
`--` correctly.
|
|
- Follow existing error-return conventions: 0 = success, 1 = usage error,
|
|
2 = bad options, 3 = missing dependency, 4+ = runtime failure.
|
|
- Prefix all local helper variables with a short unique prefix (e.g. `_taz_`)
|
|
to prevent collisions with caller-scope variables.
|
|
|
|
### Module structure
|
|
Every new module should follow this pattern:
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# <copyright block identical to existing modules>
|
|
|
|
load_conf "<module_name>"
|
|
|
|
# --- functions ---
|
|
|
|
export -f my_function
|
|
|
|
# EOF
|
|
```
|
|
|
|
Add the `load_conf` call near the top after any variable declarations.
|
|
|
|
---
|
|
|
|
## 5. Configuration keys
|
|
|
|
When adding a configurable default:
|
|
|
|
1. Use `${MY_VAR:-hardcoded_default}` in the function body.
|
|
2. Add a commented-out entry with a description to `profile.conf`.
|
|
3. Document the key in the matching table in `README.md §4.2`.
|
|
|
|
---
|
|
|
|
## 6. Theming
|
|
|
|
New theme files go in `profile.d/themes/` with a `.theme` extension.
|
|
They are **parsed, not executed** — do not add shell logic.
|
|
See the existing themes and `README.md §4.4` for the allowed syntax.
|
|
|
|
---
|
|
|
|
## 7. Running shellcheck
|
|
|
|
```bash
|
|
shellcheck -x profile.sh profile.d/*.sh
|
|
```
|
|
|
|
All warnings must be resolved before a patch will be accepted. Accepted
|
|
suppression directives (`# shellcheck disable=SCxxxx`) require an inline
|
|
comment explaining why the suppression is necessary.
|
|
|
|
---
|
|
|
|
## 8. Submitting a contribution
|
|
|
|
### Via Git (preferred)
|
|
1. Contact the maintainer to obtain push access, or fork on the Gitea instance.
|
|
2. Create a branch: `git checkout -b feature/my-feature`.
|
|
3. Commit with a clear subject line: `module: short description (≤ 72 chars)`.
|
|
4. Push and open a pull request against `master`.
|
|
|
|
### Via patch
|
|
If you do not have push access:
|
|
```bash
|
|
git format-patch origin/master
|
|
```
|
|
Send the resulting `.patch` file(s) to
|
|
`fatalerrors <at> geoffray-levasseur <dot> org`.
|
|
|
|
### Commit message format
|
|
```
|
|
module: imperative short description
|
|
|
|
Optional longer explanation of what changed and why. Wrap at 72 characters.
|
|
Reference issue numbers if applicable: closes #42.
|
|
```
|
|
|
|
---
|
|
|
|
## 9. What will be rejected
|
|
|
|
- Code requiring packages not in a minimal Debian or CentOS install.
|
|
- Use of `eval`, `source`-based config loading, or other code-injection vectors.
|
|
- Changes that break Bash 4.3 compatibility.
|
|
- Patches without a passing `shellcheck` run.
|
|
- New functions without `--help` support.
|
|
|
|
---
|
|
|
|
## 10. Financial contributions
|
|
|
|
Contact the maintainer by mail if you wish to make a financial contribution.
|