# Contribution Guidelines
*FG42* is a free software and a community of Emacs developers who like to share
their ideas and tools. We encourage you to join us. The community is what matters
to us. Here is a brief overview of contribution guidelines, which we ask all
contributors to follow.

## Asking for help
If you want to ask an usage question, first make sure to read the `README.md` file
and the documents of *FG42*. If you still need help feel free to join us via
[out gitter channel](https://gitter.im/FG42/FG42).

## Reporting issues
Issues have to be reported on our [issues tracker](https://gitlab.com/FG42/FG42/issues). Please:

- Check that the issue has not already been reported.
  - This can be achieved by searching keywords on the [issues tracker](https://gitlab.com/FG42/FG42/issues).
- Try to use a clear title, and describe your problem with complete sentences.
  - Include your emacs version and `~/.fg42.el` file as well.
  - If possible, try to include details on how to reproduce it, like a step by
    step guide.

## Contributing code
Code contributions are welcome. Please read the following sections carefully. In
any case, feel free to join us on [out gitter channel](https://gitter.im/FG42/FG42) to ask questions about
contributing!

### General contribution

#### License
The license is *GPLv2* for all parts specific to *FG42*, this includes:
- The initialization and core files
- All the built-in extensions.

For files not belonging to FG42 like local packages and libraries, refer
to the header file. Those files should not have an empty header, we may not
accept code without a proper header file.

#### Conventions
We follow these simple rules:

* Make elisp linter happy
* Make byte compiler happy `make compile`
* Follow functional patterns and avoid huge functions
* Seperate each root level expression by two new lines (e.g function definitions)
* Put `(comment ...)` expression after each macro/function to demonstrate the usage.
* Write good docstrings
* Choose meaningful names
* Follow the indentation guides made in FG42
* Prefix the functions with a prefix to differentiate them from other functions.
  for example `fg42-namespace/functoin-name`.
* use `<prefix>/-<fn-name>` for private/internal function names
* use `/` to categorize functions into namespaces (air quote)

#### Pull-Request
Submit your contribution against the `master` branch. The `stable` branch
is going to be our last stable version only.

Please make one PR per feature. Keep your PRs as small as possible so we can review them
easily. Don't forget to make the byte compiler and the linter happy. There should not
be any build error or warning on `make compile`. We like how [Linus Torvalds thinks
about build warnings](https://linuxreviews.org/Linus_Torvalds#On_Build-Testing).

Write commit messages according to adapted [this article](https://chris.beams.io/posts/git-commit/):

- Include the extension or library name in the title inside square brackets
- Use present tense and write in the imperative: “Fix bug”, not “fixed bug” or
  “fixes bug”.
- Start with a capitalized, short (72 characters or less) summary, followed by a
  blank line.
- If necessary, add one or more paragraphs with details, wrapped at 72
  characters.
- Separate paragraphs by blank lines.

This is a model commit message:

```
[FPKG] Capitalized, short (72 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

    - Typically a hyphen or asterisk is used for the bullet, followed by a
      single space, with blank lines in between, but conventions vary here

    - Use a hanging indent
```

[[https://github.com/magit/magit/][Git Commit]] and [[https://github.com/magit/magit/][Magit]] provide Emacs mode
for Git commit messages, which helps you to comply to these guidelines.

### Contributing an extension
Technical aspects TBD

Each file should be GPL compliant and contain the following header:

```lisp
;;; FILENAME --- SHORT DESCRIPTION
;;
;; Copyright (c) 2010-2020 Sameer Rahmani & Contributors
;;
;; Author: YOUR FULL NAME <YOUR EMAIL>
;; URL: https://gitlab.com/FG42/FG42
;; Version: VERSION
;;
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
;;
;;; Commentary:
;; THE COMMENTARY ON THE MOST IMPORTANT ASPECT OF THE EXTENSION
;;
;;; Code:
```

You should replace `FILENAME` by the name of the file (e.g. `packages.el`).
Don't forget to replace `YOUR FULL NAME` and `YOUR EMAIL` also.

#### Contribute to an existing extension
If you are contributing to an already existing extension, you should not modify any
header file.

* Credits

This `CONTRIBUTING` file is partially based on the [Rails Contribution
guidelines](https://github.com/rails/rails/blob/master/CONTRIBUTING.md)
and [Flycheck Contribution guidelines](https://github.com/flycheck/flycheck/blob/master/CONTRIBUTING.md)
and [Spacemacs Contribution guidelines](https://raw.githubusercontent.com/syl20bnr/spacemacs/master/CONTRIBUTING.org).
