diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org new file mode 100644 index 0000000..a8ce492 --- /dev/null +++ b/CONTRIBUTING.org @@ -0,0 +1,87 @@ +#+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 +~eshell-info-banner.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 +Eshell” 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) + +*** 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 | diff --git a/README.org b/README.org index e6e4310..210fc79 100644 --- a/README.org +++ b/README.org @@ -16,6 +16,14 @@ This package is geared towards Linux in particular, I am pretty sure it will not work on Windows, and there will probably be bugs on macOS. PR are welcome if you want to fix that! +* Table of Contents :TOC_2_gh: +- [[#introduction][Introduction]] +- [[#installation][Installation]] +- [[#customizing][Customizing]] +- [[#my-computer-doesnt-have-a-battery-will-this-still-work][My computer doesn’t have a battery, will this still work?]] +- [[#contributing][Contributing]] +- [[#license][License]] + * Installation A couple of options are available for installing ~eshell-info-banner.el~. The first one is to clone the repository in @@ -112,17 +120,8 @@ detect whether you have a battery or not/ and will only display this line if you have one. If you don’t have a battery, the only difference is you will have one less line than laptop users. -* Upcoming changes -Here are some upcoming changes I hope I’ll make in the future. If you -see a feature still hasn’t been implemented and you wish to implement -it, don’t hesitate to contribute and submit a PR! - -** Better support for other OSes -Displaying the OS name only works on Linux systems that have an -~/etc/os-release~ file and ~df~ available in Eshell’s path, or on Windows -at least partially —i.e. it will probably not work correctly on macOS -and on exotic Linux distributions. This should be fixed someday. (And -*BSD maybe?) See [[https://github.com/Phundrak/eshell-info-banner.el/issues/4][this issue]]. +* Contributing +See [[file:CONTRIBUTING.org]]. * License ~eshell-info-banner.el~ is available under the GNU GPL-3.0 license. You