93 lines
5.1 KiB
Org Mode
93 lines
5.1 KiB
Org Mode
|
#+title: Contributing
|
|||
|
#+author: Lucien Cartier-Tilet
|
|||
|
#+email: lucien@phundrak.com
|
|||
|
First of all, thank you for being interested in contributing! You rock!
|
|||
|
|
|||
|
In this document, you will find some guidelines for contributing to
|
|||
|
~TEMPLATE-NAME.el~. These are more guidelines than rules, so don’t try
|
|||
|
too hard to follow them.
|
|||
|
|
|||
|
* Table of Contents :TOC_5_gh:
|
|||
|
- [[#how-can-i-contribute][How Can I Contribute?]]
|
|||
|
- [[#submitting-bugs-and-errors][Submitting Bugs and Errors]]
|
|||
|
- [[#submitting-new-code][Submitting New Code]]
|
|||
|
- [[#git-commit-messages][Git Commit Messages]]
|
|||
|
- [[#describing-the-pull-request][Describing the Pull Request]]
|
|||
|
- [[#finding-something-to-do][Finding Something To Do]]
|
|||
|
- [[#issue-labels][Issue Labels]]
|
|||
|
|
|||
|
* How Can I Contribute?
|
|||
|
** Submitting Bugs and Errors
|
|||
|
The easiest way to contribute is to the project is if you encounter a
|
|||
|
bug or an error. If you encounter one, check whether there is an issue
|
|||
|
already opened. If not, you can open one! Try to provide as much
|
|||
|
information as possible:
|
|||
|
- Are you running the latest version of the package?
|
|||
|
- Which version of Emacs are you running? On what system?
|
|||
|
- What is your configuration for this package?
|
|||
|
- What is the error message? Do you have a debug trace for the error?
|
|||
|
- Can you reproduce it consistently? If so, how?
|
|||
|
- What would the expected behavior be?
|
|||
|
As you are collecting these pieces of information, try to come up with
|
|||
|
a short and clear issue title –it should describe quickly your issue
|
|||
|
without being too vague (e.g. “doesn’t work”).
|
|||
|
|
|||
|
** Submitting New Code
|
|||
|
If you are submitting new code through a pull request, make sure of
|
|||
|
the following:
|
|||
|
- Your code doesn’t do something already implemented in the package;
|
|||
|
- Your code follows the Emacs Lisp style guide presented [[https://github.com/bbatsov/emacs-lisp-style-guide][here]] as best
|
|||
|
as you can;
|
|||
|
- All new functions and variables declared through ~defvar~, ~defcustom~,
|
|||
|
and ~defconst~ have docstrings;
|
|||
|
- All new customizable variables declared through ~defcustom~ must
|
|||
|
belong to a group and have its version declared for the next minor
|
|||
|
revision, i.e. if the current version is ~1.2.3~, the new variable
|
|||
|
must be declared for version ~1.2.4~;
|
|||
|
- If you introduced new dependencies in your code, you also added them
|
|||
|
to the list of dependencies in the file’s headers;
|
|||
|
- And obviously, your code works (I include that because I myself
|
|||
|
sometimes push commits that don’t work). To make sure of that, don’t
|
|||
|
hesitate to restart Emacs to make sure any variable or function you
|
|||
|
might have deleted is unloaded.
|
|||
|
|
|||
|
*** Git Commit Messages
|
|||
|
Your commits should also follow [[https://github.com/syl20bnr/spacemacs/blob/develop/CONTRIBUTING.org#commit-messages][Spacemacs’ guidelines]] on this matter,
|
|||
|
especially:
|
|||
|
- Lines no longer than 72 characters
|
|||
|
- Explain what you did
|
|||
|
- Use the imperative in your summary
|
|||
|
- Use present tense and imperative for what your commit changes
|
|||
|
|
|||
|
*** Describing the Pull Request
|
|||
|
When opening a new pull request, check that its title is short and
|
|||
|
clear as to what it is meant to do. Its description should:
|
|||
|
- Provide the current behavior of the package, and how it will modify it
|
|||
|
- If it is linked to an open issue, mention it
|
|||
|
- If you are submitting an enhancement pull request, describe why this
|
|||
|
code suggestion would be useful
|
|||
|
|
|||
|
** Finding Something To Do
|
|||
|
Not sure where to begin? Take a look at the list of open issues,
|
|||
|
especially the ones with one of the following labels:
|
|||
|
- [[https://github.com/Phundrak/eshell-info-banner.el/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22][/good first issue/]] :: These issues indicate easy to fix issues and
|
|||
|
easy to implement enhancements. If you are a beginner or if you want
|
|||
|
to familiarize yourself with the package, look for these issues.
|
|||
|
- [[https://github.com/Phundrak/eshell-info-banner.el/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+sort%3Aupdated-desc][/help wanted/]] :: These issues might require some more work than /good
|
|||
|
first issue/ issues and might be a bit more interesting.
|
|||
|
If you want to work on an open issue, leave a comment saying
|
|||
|
so. However, you can directly submit a pull request if you are simply
|
|||
|
adding support for a non-standard Linux distribution.
|
|||
|
|
|||
|
* Issue Labels
|
|||
|
| Label | Description |
|
|||
|
|------------------+---------------------------------------------------------------------|
|
|||
|
| enhancement | Feature request |
|
|||
|
| good first issue | easy to fix issue |
|
|||
|
| bug | Confirmed bug or something very likely to be a bug |
|
|||
|
| help wanted | This bug might not be my priority, so feel to give it a try! |
|
|||
|
| documentation | There is something wrong with the documentation |
|
|||
|
| duplicate | The issue has already been reported |
|
|||
|
| invalid | Issue isn’t valid (not the package’s fault) |
|
|||
|
| wontfix | It’s either working as intended, or I decided not to fix it for now |
|