updated and fixed doc (markdown spellcheck)

This commit is contained in:
fatalerrors
2026-05-28 18:08:41 +02:00
parent 481cc94fa8
commit 3e0bedd9c8
5 changed files with 219 additions and 28 deletions

View File

@@ -39,6 +39,7 @@ to target). Stale forks cause avoidable merge conflicts.
**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`.
@@ -71,13 +72,15 @@ 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:
```bash
# Debian / Ubuntu
apt-get install shellcheck
@@ -94,6 +97,7 @@ 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.
@@ -109,6 +113,7 @@ brew install shellcheck
`${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.
@@ -120,6 +125,7 @@ brew install shellcheck
to prevent collisions with caller-scope variables.
### Module structure
Every new module should follow this pattern:
```bash
@@ -172,20 +178,25 @@ 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:
```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
@@ -197,7 +208,7 @@ Reference issue numbers if applicable: closes #42.
## 11. What will be rejected
- Code requiring packages not in a minimal Debian or CentOS install.
- Code requiring packages not in a minimal Debian or CentOS install, unless optionnal.
- 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.