# 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 `/-` 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 ;; 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 . ;; ;;; 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).