#+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
~archwiki.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. avoid stuff like “error when opening
Firefox” or “doesn’t work”).

If you want to report issues related to the ArchWiki itself, please do
it so there. This package is only a helper package for viewing a
locally available copy of the ArchWiki.

** 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 |