https://github.com/carbslinux/contributing

Contribution Guidelines
https://github.com/carbslinux/contributing

Last synced: about 2 months ago
JSON representation

Contribution Guidelines

• Host: GitHub
• URL: https://github.com/carbslinux/contributing
• Owner: CarbsLinux
• License: cc0-1.0
• Created: 2020-05-04T15:30:57.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2020-05-04T19:50:13.000Z (almost 6 years ago)
• Last Synced: 2025-01-29T07:30:38.270Z (about 1 year ago)
• Homepage:
• Size: 10.7 KB
• Stars: 0
• Watchers: 2
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
Carbs Linux Contribution Guidelines

===================================

Thanks for taking your time to contribute! To maintain stylistic

behaviour throughout the repositories, you must adhere to these

guidelines. Exceptions may occur with good reasoning.

**Table of Contents**

- [Carbs Linux Contribution Guidelines](#carbs-linux-contribution-guidelines)

    - [General Conventions](#general-conventions)

    - [Shell Conventions](#shell-conventions)

    - [Plaintext Conventions (MarkDown)](#plaintext-conventions-markdown)

    - [Git Conventions](#git-conventions)

    - [C Conventions](#c-conventions)

General Conventions

-------------------

These apply to each and every file on our repositories.

- Try to keep the file readable.

  - Characters on a line shouldn't exceed 100 characters excluding indentation.

  - Make sure you don't have code commented out during commit. Uncomment them or

    remove them.

  - Do not add comments following the code, add them to the top of the code. It

    makes it harder to read, and lines longer.

Comments should look like this.

    # Good way of commenting

    your code goes here

    

    your code goes here  # Bad way of commenting

Shell Conventions

-----------------

Shell is central to Carbs Linux projects. Most of the tools

and packages are written in POSIX sh.

- Use 4 spaces for indentation, instead of tabs.

- Make sure you don't use bash-specific code.

- Make sure you lint your code with `shellcheck` and if you

  are new to POSIX sh, use `checkbashisms`.

- Don't spawn new processes if you don't absolutely need to.

  Especially during string manipulation.

  - Never use awk. Use sed to a string if it is a complex string

    manipulation.

  - Instead of `basename $file` you should do `file=${file##*/}`.

  - Instead of `dirname  $file` you should do `file=${file%/*}` .

  - If `$file` has a suffix (`.asc`) you want to remove, instead of

    `basename $file .asc` you should do `file=${file##*/} file=${file%.asc}`.

Plaintext Conventions (MarkDown)

-------------------------------

Markdown and Plaintext conventions are the same. Even if you are

editing a Markdown file you should make it readable plaintext.

If a user downloads the repository, they should be able to read

it without the help of Github rendering it. Most repositories on

Github fail to do this, making their README file completely

unreadable when somebody decides to clone the Git repository.

**Headings**

Instead of `#` and `##` for headings use `=====` and `-----`

respectively. Using `#` is simpler, but underlines such as the

latter, give a natural sense of depth to the reader. Usage of

`###` for headers are okay as there is no replacement for them.

Headings should have 2 preceding empty lines, and should be followed

with a single empty line.

**Code Blocks**

Instead of ``` (three backticks) for code blocks, use 4 spaces

of indentation. Again, this gives the user a better sense of

depth when reading the file in plaintext.

**Links**

Instead of using `[link description](https://example.com/location)`,

prefer the following format.

    [link description]

    

    

    At the end of the section/file

    [link description]: https://example.com/location

**Italic and Bold Faces**

In markdown `_italics_` and `*italics*`, and `**bold**` and `__bold__`

produce the same output. However, prefer `_italics_` and `**bold**`

since they are easier to distinguish and make sense of.

Git Conventions

---------------

- You should commit a single change at a time. If you have

  multiple unrelated changes in your file, commit them seperately.

- In contrast, if you have multiple related changes across multiple

  files, commit them together.

Your commit message should be in the following format

    : 

    

    Further long explanation that can be viewed

    in the long git logs or patches. (optional)


Here is an example commit from [kiss]

    kiss: better manifest checking

    

    This introduces a few changes in manifest checking.

    * If KISS_FORCE is specified, we don't check the manifest.

    * This will show every missing file, and won't die in the first manifest issue.

    * kiss will announce dependency checking after manifest checking is complete.

**Exceptions**

Exceptions are made for documentation, as it can be tedious to prepare

in different hunks and such. There can be punctuation and spelling

mistakes to fix. Just commit them with `file: update` where file stands

for the name of the file.

[kiss]: https://github.com/CarbsLinux/kiss

C Conventions

-------------

C is currently only used in the package manager itself, so these are

small, and restrictive guidelines.

- Use 2 spaces for indentation.

- If a portable program exists, don't bother reimplementing it.

- Don't use any header outside of the standard C library. The reason

  C programs exist in the package manager is to ensure portability.

  That's why you should never, ever use a header that isn't in `libc`.