2020-04-14 22:37:00 +01:00
|
|
|
# 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
|
2020-04-15 16:21:55 +01:00
|
|
|
* Make byte compiler happy `make compile`
|
2020-04-14 22:40:40 +01:00
|
|
|
* 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)
|
2020-04-14 22:37:00 +01:00
|
|
|
|
|
|
|
#### 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
|
2020-04-15 16:21:55 +01:00
|
|
|
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).
|
2020-04-14 22:37:00 +01:00
|
|
|
|
|
|
|
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).
|