# Contribution Guide

## How to contribute

### Issues

You can freely create an issue using the following links:

- Report and fixes for bugs and performance issues [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=bug_report.md)
- Questions on usage [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=feature_request.md)
- Feature request [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=help.md)
- Others (suggestions, projects, discussion, complaints, news, information or anything) [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=free_style.md)

### Pull requests

We always welcome following types of pull requests. Any changes will be considered to be provided under the BSD 3-Clause License.
If you do not know whether your changes would be appropriate for merge, please feel free to create a pull request and let us talk with each other!

- Better translation to English, typo fixes
- Fixes, optimization, test cases
- New features
- New color themes ... We accept new themes in [`contrib`](https://github.com/akinomyoga/blesh-contrib/pulls) repository.
- Others

### Wiki

You can freely edit [wiki pages](https://github.com/akinomyoga/ble.sh/wiki).

- Translations
- Typo fixes
- Create new pages

## For package maintainers

If you are a package maintainer for a repository of Linux distribution, etc.
you may provide a package-specific setting by preparing
a file `/path/to/blesh/lib/_package.sh` (e.g. `/usr/share/blesh/lib/_package.sh`)
which will be sourced after the load of `ble.sh` just before sourcing user's configuration (`~/.blerc`).

- In the file, the shell variable `_ble_base_package_type=TYPE` should be
   set up to have a repository-specific name (such as `AUR`). 

- The function named `ble/base/package:TYPE/update` (where `TYPE`
  matches with a value assigned to `_ble_base_package_type`) may be
  provided to define a custom updating procedure.  The exit status of the function can be
  - `0` ... when the update successed
  - `6` ... when the update was skipped because the package was up to date.
  - `125` ... when it wants to fallback to the built-in updating procedure of `ble.sh`.
  - Other ... when the update failed

An example `lib/_package.sh` might be

```bash
_ble_base_package_type=apt

function ble/base/package:apt/update {
  sudo apt upgrade blesh
}
```

You can also find a real example for AUR (Arch User Repository) [here](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git).

## Summary of codebase

The core script file `ble.sh` is generated by combining the following files:

- `ble.pp` ... Basic initialiation
- `src/def.sh` ... Prototype definitions
- `src/util.sh` ... Basic utility functions
- `src/decode.sh` ... User-input decoder and keybindings
- `src/color.sh` ... Terminal graphic attributes
- `src/canvas.sh` ... Terminal layout engine
  - `src/canvas.emoji.sh` ... Emoji database
- `src/history.sh` ... Command history management
- `src/edit.sh` ... Line editor
- `src/benchmark.sh` ... Measure processing time
- `lib/core-completion.sh` ... Prototype definition for completions
- `lib/core-syntax.sh` ... Prototype definitions for syntax analyzer

Useful features are implemented in separate modules:

- `keymap/vi.sh` ... Vim mode
  - `lib/vim-arpeggio.sh` ... `vim-arpeggio`-like plugin
  - `lib/vim-surround.sh` ... `vim-surround`-like plugin
- `keymap/emacs.sh` ... Emacs mode
- `lib/core-syntax.sh` ... Shell parser and syntax highlighting
  - `lib/core-syntax-ctx.def` ... Definition of parser states
- `lib/core-complete.sh` ... Completions including `menu-complete`, `auto-complete`, `menu-filter`, `dabbrev`, `sabbrev`, etc.

The following files are initialization scripts:

- `lib/init-term.sh` ... Initialize terminal escape sequences (host-to-terminal, i.e. control sequences)
- `lib/init-cmap.sh` ... Initialize terminal escape sequences (terminal-to-host, i.e. key sequences)
- `lib/init-bind.sh` ... Initialize readline attacher
- `lib/init-msys1.sh` ... Workaround for MSYS1 with broken pipes
  - `lib/init-msys1-helper.c` ... Helper C program for the workaround of broken pipes

## Tests

Tests can be run by one of the following commands:

```bash
$ make check
$ make check-all
$ bash out/ble.sh --test

```

Currently test coverage is very small
partly because the testing for interactive behavior and terminal rendering results is hard.
Nevertheless, the tests are defined in the following files:

- `lib/core-test.sh` ... Library for tests
- `lib/test-main.sh`
- `lib/test-util.sh`
- `lib/test-canvas.sh`
- `lib/test-edit.sh`
- `lib/test-complete.sh`
- `lib/test-syntax.sh`