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. Branch policy

Branch	Purpose
master	Main development branch — new features and enhancements go here
<version> (e.g. 3.x)	Maintenance branch for a released version — bugfixes backported from master

New functionality must always target master.

Bugfixes must target the branch where the bug was introduced:

• If the bug exists in a released version, open the fix against that version's maintenance branch first, then cherry-pick onto master.
• If the bug is only in master (unreleased), fix it directly on master.
• During a release-candidate cycle, bugfixes go on the x.* branch and are merged back into master before the final release.

Do not add new features to a maintenance branch.

---

4. Versioning scheme

Versions follow the format MAJOR.MINOR.PATCH where the MINOR number conveys the development stage of the next major release:

Minor range	Stage	Rules
x.90.y	Alpha toward x+1	Stays on master. Development is open: new features are welcome, regressions are acceptable.
x.95.y	Beta toward x+1	The x+1.* maintenance branch is created at this point. No regression unless absolutely necessary; new features still allowed.
x.99.y	RC toward x+1	Bugfixes only. No new features. No regression allowed. Becomes x+1.0.0 when stable.

Examples: 3.90.1 is the first alpha toward 4.0, 3.99.2 is the second release candidate for 4.0.

The PATCH number increments freely within a stage. A bump in MINOR (e.g. 90 → 95) always indicates a stage promotion in development phase.

Any experimental version must have it's dedicated branch.

---

5. Development environment

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

---

6. 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. Prefer upper case for global and lowercase for local.
• printf instead of echo all the time.
• 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.

---

7. 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.

---

8. 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.

---

9. 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.

---

10. 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.

---

11. 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.

---

12. Financial contributions

Contact the maintainer by mail if you wish to make a financial contribution.