org-unique-id/CONTRIBUTING.org

#+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
~org-unique-id~. 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]]
    - [[#ensuring-the-quality-of-your-code][Ensuring the quality of your 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
org-mode” or “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
- 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)

*** Ensuring the quality of your code
Although a CI is already in place on the Github repository, you are
encouraged to make sure yourself everything runs correctly.

This package uses [[https://github.com/emacs-eask/eask][Eask]] to run its linters. Once it is installed, you
can go to your preferred terminal and run ~make ci~. If everything goes
well, you’re ready to submit your code to the repository. If not,
please fix whatever Eask complains about first.

*** 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/org-unique-id/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/org-unique-id/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 |