|
| 1 | +#Repository Guidelines |
| 2 | + |
| 3 | +##Dos and Don'ts |
| 4 | + |
| 5 | +-**Do** regenerate the distribution scripts with`./generator.sh` whenever you touch`generator.sh` or`color table.txt`; commit the resulting`dist/ColorEcho.*` updates together. |
| 6 | +-**Do** run targeted checks (`shellcheck`,`shfmt`,`./test-scripts/<shell>`) only on the files you touched to keep diffs focused; the CI pipeline still runs the full matrix. |
| 7 | +-**Do** honor the 2-space indentation defined in`.editorconfig` for shell and Markdown files. |
| 8 | +-**Don't** edit the files under`dist/` by hand; they are generated output and will be overwritten by`./generator.sh`. |
| 9 | +-**Don't** mass-format or rewrite unrelated scripts; align with the existing naming and function structure produced by the generator. |
| 10 | + |
| 11 | +##Project Structure and Module Organization |
| 12 | + |
| 13 | +ColorEchoForShell ships colorized`echo` helpers for multiple shells. |
| 14 | + |
| 15 | +-`dist/ColorEcho.{bash,sh,ksh,zsh,fish}`: generated shell-specific helpers; source this directory in user scripts. |
| 16 | +-`generator.sh`: builds the contents of`dist/`; relies on`color table.txt` for color codes. |
| 17 | +-`color table.txt`: canonical mapping of color names to ANSI codes. |
| 18 | +-`test-scripts/<shell>`: runtime smoke tests that source the matching dist file and exercise every function. |
| 19 | +-`.travis.yml`: Travis CI pipeline defining the canonical lint, format, and runtime test matrix. |
| 20 | +-`.editorconfig`,`.markdownlint.json`: repository formatting and Markdown lint rules. |
| 21 | +-`README.md`,`Demo.*`: project overview and assets. |
| 22 | + |
| 23 | +##Build, Test, and Development Commands |
| 24 | + |
| 25 | +All commands assume the repository root as the working directory. |
| 26 | + |
| 27 | +- Regenerate distribution scripts:`./generator.sh` |
| 28 | +- Run ShellCheck on touched files, e.g.`shellcheck generator.sh`,`shellcheck dist/ColorEcho.sh`,`shellcheck dist/ColorEcho.ksh`, or`shellcheck dist/ColorEcho.bash` |
| 29 | +- Format updated shell scripts with the CI image:`docker run -it --rm -v "$(pwd)":/sh -w /sh peterdavehello/shfmt:3.3.0 shfmt -sr -i 2 -ci -w generator.sh` (replace`generator.sh` with any touched source files). Keep the`peterdavehello/shfmt:3.3.0` tag aligned with`.travis.yml`. |
| 30 | +- Lint Markdown with the CI image:`docker run -it --rm -v "$(pwd)":/md peterdavehello/markdownlint markdownlint '**/*.md'` |
| 31 | +- Validate dist output in bash:`./test-scripts/bash` (replace`bash` with`sh`,`ksh`,`zsh`, or`fish` for other shells) |
| 32 | + |
| 33 | +Install`echint` (`npm install -g echint`) to mirror the CI`.editorconfig` check and run`echint`. |
| 34 | + |
| 35 | +##Coding Style and Naming Conventions |
| 36 | + |
| 37 | +- Shell and Markdown files use 2-space indentation, UTF-8, and trimmed trailing whitespace per`.editorconfig`. |
| 38 | +- Keep function and file names consistent with the generator output (`echo.<Style><Color>`); new helpers must be added through`generator.sh`. |
| 39 | +- Comments and user-facing text are written in en-US; match the concise style in`dist/ColorEcho.*`. |
| 40 | +- When formatting shell scripts, rely on`shfmt` with`-sr -i 2 -ci` to stay aligned with CI. |
| 41 | + |
| 42 | +##Testing Guidelines |
| 43 | + |
| 44 | +- Use the scripts under`test-scripts/` to exercise the generated output for the corresponding shell; they exit on first failure. |
| 45 | +- Prefer running only the variants impacted by your changes (e.g., run`./test-scripts/ksh` after updating`generator.sh` in a way that affects the ksh output). |
| 46 | +- Runtime tests depend on the availability of each shell binary; install the shell locally if it is missing. |
| 47 | +- If you modify color definitions or generator logic, rerun all shell variants to ensure parity. |
| 48 | + |
| 49 | +##Commit and Pull Request Guidelines |
| 50 | + |
| 51 | +- Follow the prevailing style: imperative, capitalized subjects without trailing periods (e.g.,`Add markdownlint test on Travis CI`), optional descriptive body wrapped at 72 chars. |
| 52 | +- Keep commits focused, commit generated`dist/` changes with their source updates, and ensure all configured checks in`.travis.yml` pass. |
| 53 | +- Reference related issues or PRs in the body when relevant and note environment prerequisites for reviewers. |
| 54 | + |
| 55 | +##Safety and Permissions |
| 56 | + |
| 57 | +- Ask before adding dependencies, deleting files, or altering CI configuration; keep edits scoped to the problem at hand. |
| 58 | +- Do not run destructive commands or rename generated files; rely on`generator.sh` for updates. |
| 59 | +- You may freely read files, run targeted linters/tests, and create small patches; confirm large or cross-cutting changes with the maintainer. |
| 60 | +- Exclude secrets or environment-specific data from commits and documentation. |