profile/doc/CONTRIBUTING.md

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 to see if your idea is already planned.
• Check the issue tracker 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:

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:

# 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:

#!/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

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:

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.