neofetch/CONTRIBUTING.md

# How to Contribute

<!-- vim-markdown-toc GFM -->

* [Coding Conventions](#coding-conventions)
    * [ShellCheck](#shellcheck)
    * [No no's](#no-nos)
    * [If Statements](#if-statements)
    * [Case Statements](#case-statements)
* [Making changes to Neofetch](#making-changes-to-neofetch)
    * [Adding support for a new Operating System / Distribution.](#adding-support-for-a-new-operating-system--distribution)

<!-- vim-markdown-toc -->


## Coding Conventions

- Use `bash` built-ins wherever possible.
- Try not to pipe (`|`) at all.
- Limit usage of external commands `$(cmd)`.
- Indent 4 spaces.
- Use [snake_case](https://en.wikipedia.org/wiki/Snake_case) for function
  and variable names.
- Keep lines below `100` characters long.
- Use `[[ ]]` for tests.
- Double Quote **EVERYTHING**.
- Don’t use single quotes, except for special cases.

### ShellCheck

For your contribution to be accepted, your changes need to pass
ShellCheck.

Run ShellCheck with the following command:

```sh
# Why do we exclude numerous tests?
# See: https://github.com/dylanaraps/neofetch/wiki/Shellcheck-Exclusions
shellcheck neofetch -e SC1090,SC2009,SC2012,SC2016,SC2034,SC2128,SC2153,SC2154,SC2178,SC2010,SC1004,SC1091,SC1117
```

**Note**: If you have trouble installing ShellCheck. You can open a pull
request on the repo and our Travis.ci hook will run ShellCheck for you.


### No no's

- Don’t use GNU conventions in commands.
    - Use POSIX arguments and flags.
- Don’t use `cut`.
    - Use `bash`'s built-in [parameter expansion](http://wiki.bash-hackers.org/syntax/pe).
- Don’t use `echo`.
    - Use `printf "%s\n"`
- Don’t use `bc`.
- Don’t use `sed`.
    - Use `bash`'s built-in [parameter expansion](http://wiki.bash-hackers.org/syntax/pe).
- Don’t use `cat`.
    - Use `bash`'s built-in syntax (`file="$(< /path/to/file.txt)")`).
- Don’t use `grep "pattern" | awk '{ printf }'`.
    - Use `awk '/pattern/ { printf }'`


### If Statements

If the test only has one command inside of it; use the compact test
syntax. Otherwise the normal `if`/`fi` is just fine.

```sh
# Bad
if [[ "$var" ]]; then
    printf "%s\n" "$var"
fi

# Good
[[ "$var" ]] && printf "%s\n" "$var"

# Also good (Use this for longer lines).
[[ "$var" ]] && \
    printf "%s\n" "$var"
```


### Case Statements

Case statements need to be formatted in a specific way.

```sh
# Good example (Notice the indentation).
case "$var" in
    1)  printf "%s\n" 1 ;;
    2)
        printf "%s\n" "1"
        printf "%s\n" "2"
    ;;

    *)
        printf "%s\n" "1"
        printf "%s\n" "2"
        printf "%s\n" "3"
    ;;
esac
```

## Making changes to Neofetch

### Adding support for a new Operating System / Distribution.

Adding support for a new OS/Distro requires adding the Name, Logo and
Colors of the OS/Distro to the `get_distro_ascii()` function.

The function is located right at the bottom of the script, one function
above `main()`. Inside this function you’ll find an alphabetical list of
each OS/Distro.

Find the spot in the list your new OS/Distro fits into and start
implementing your changes.

If your OS/Distro requires changes to the actual information gathering
functions then you can make these changes in the `get_*` functions.

**Syntax**:

- You have to escape back-slashes (`\`). (eg `\\`)
- You can use `${c1}` to `${c6}`to color the ascii.
    - These are evaluated *after* we read the file.


**Example**:

```sh
        "CRUX"*)
            set_colors 4 5 7 6
            read -rd '' ascii_data <<'EOF'
${c1}         odddd
      oddxkkkxxdoo
     ddcoddxxxdoool
     xdclodod  olol
     xoc  xdd  olol
     xdc  ${c2}k00${c1}Okdlol
     xxd${c2}kOKKKOkd${c1}ldd
     xdco${c2}xOkdlo${c1}dldd
     ddc:cl${c2}lll${c1}oooodo
   odxxdd${c3}xkO000kx${c1}ooxdo
  oxdd${c3}x0NMMMMMMWW0od${c1}kkxo
 oooxd${c3}0WMMMMMMMMMW0o${c1}dxkx
docldkXW${c3}MMMMMMMWWN${c1}Odolco
xx${c2}dx${c1}kxxOKN${c3}WMMWN${c1}0xdoxo::c
${c2}xOkkO${c1}0oo${c3}odOW${c2}WW${c1}XkdodOxc:l
${c2}dkkkxkkk${c3}OKX${c2}NNNX0Oxx${c1}xc:cd
${c2} odxxdx${c3}xllod${c2}ddooxx${c1}dc:ldo
${c2}   lodd${c1}dolccc${c2}ccox${c1}xoloo
EOF
        ;;
```