org-unique-id/CONTRIBUTING.org

98 lines
5.3 KiB
Org Mode
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

#+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 dont 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
Eshell” or “doesnt work”).
** Submitting New Code
If you are submitting new code through a pull request, make sure of
the following:
- Your code doesnt 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 files headers
- And obviously, your code works (I include that because I myself
sometimes push commits that dont 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, youre 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/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 isnt valid (not the packages fault) |
| wontfix | Its either working as intended, or I decided not to fix it for now |