doomemacs/docs/contributing.org

#+TITLE: Contributing
#+STARTUP: nofold

I can't say Doom Emacs is a one man show anymore. It wouldn't have gotten this
far without the help of folks like you! Still, I struggle to maintain it all;
especially the modules I do not use. If Doom has been useful to you, consider
pitching in and helping me out.

Help can range from reporting bugs, proposing enhancements, submitting code and
documentation, or just spreading the good word. To ensure no toes get stepped on
or wires crossed, this guide was created to help you help us.

* Table of Contents :TOC_3:
- [[#where-can-i-help][Where can I help?]]
- [[#reporting-issues][Reporting issues]]
  - [[#collect-backtraces-of-any-error-messages][Collect backtraces of any error messages]]
  - [[#create-a-step-by-step-reproduction-guide][Create a step-by-step reproduction guide]]
  - [[#include-information-about-your-doom-install][Include information about your Doom install]]
  - [[#debugging-crashes-with-gdb][Debugging crashes with gdb]]
- [[#suggesting-features-keybinds-andor-enhancements][Suggesting features, keybinds and/or enhancements]]
- [[#contributing-code][Contributing code]]
  - [[#conventions][Conventions]]
    - [[#code-style][Code style]]
    - [[#naming-conventions][Naming conventions]]
    - [[#commits--prs][Commits & PRs]]
    - [[#keybind-conventions][Keybind conventions]]
  - [[#your-first-code-contribution][Your first code contribution]]
  - [[#submitting-pull-requests][Submitting pull requests]]
  - [[#contributing-to-doom-core][Contributing to Doom core]]
  - [[#contributing-to-an-existing-module][Contributing to an existing module]]
  - [[#contributing-a-new-module][Contributing a new module]]
- [[#contributing-documentation][Contributing documentation]]
  - [[#contributing-to-dooms-manual][Contributing to Doom's manual]]
  - [[#contributing-module-documentation][Contributing module documentation]]
- [[#other-ways-to-support-doom-emacs][Other ways to support Doom Emacs]]
- [[#special-thanks][Special thanks]]

* Where can I help?
+ Our [[https://github.com/hlissner/doom-emacs/issues][issue tracker]] has many issues. If you find one that you have an answer to,
  please don't hold back!
+ Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/good%20first%20issue][good first issue]]. These were judged to have a low
  barrier of entry.
+ Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/help%20wanted][help wanted]]. These tend to be a little (or a lot)
  harder, and are issues outside my own expertise.
+ If you've encountered a bug, [[https://github.com/hlissner/doom-emacs/issues/new/choose][file a bug report]].
+ The [[https://github.com/hlissner/doom-emacs/projects/3][development roadmap board]] is a rough timeline of what is being worked on
  and when. It will give you some idea of what will change and where you can
  redirect your efforts.
+ The [[https://github.com/hlissner/doom-emacs/projects/2][plugins under review board]] lists third party plugins being considered (or
  rejected) for inclusion in Doom Emacs. Approved and unclaimed packages are
  open for you to implement yourself.
+ The [[https://github.com/hlissner/doom-emacs/projects/5][upstream bugs board]] lists known issues that have external causes, but
  affect Doom. If you're feeling adventurous (or are better acquainted with the
  cause) perhaps you can address them at the source.

* TODO Reporting issues
So you've found a problem. Before you fire off that bug report, there are a few
things you should try first:

+ Make sure your configuration (or Doom Emacs) is *not* byte-compiled. Run ~doom
  clean~ to ensure it isn't. *Byte-compilation interferes with debugging!*
+ Run ~bin/doom refresh~ to ensure all plugins are installed and autoload files
  generated.
+ Run ~bin/doom doctor~ to diagnose common issues with your system.
+ Check [[file:faq.org::*Common%20Issues][Common Issues]] in the FAQ to see if yours is a known issue.
+ If you happen to know what module(s) are relevant to your issue, check their
  documentation (press =<leader> h m= to jump to a module's documentation). Your
  issue may be documented.
+ If possible, check if the issue can be reproduced in vanilla Emacs (Emacs
  without Doom) and/or vanilla Doom (Doom without your private config). To test
  this, use ~M-x doom/sandbox~ (bound to =<leader> h E=). [[file:getting_started.org::*Use the sandbox][A guide for using the
  sandbox can be found in the manual]].
+ Make sure your issue hasn't already been reported by searching the [[https://github.com/hlissner/doom-emacs/issues][issue
  tracker]].
+ Make sure your issue hasn't been resolved on the =develop= branch of Doom.

If these suggestions haven't worked for you, it's time [[https://github.com/hlissner/doom-emacs/issues/new/choose][to write a bug report]].
Please make sure of the following before you submit:

** TODO Collect backtraces of any error messages

** TODO Create a step-by-step reproduction guide

** TODO Include information about your Doom install

** TODO Debugging crashes with gdb

* TODO Suggesting features, keybinds and/or enhancements

* TODO Contributing code
There's much to be done around here! We need bugfixes, new features, and
documentation. If you'd like to convert some caffeine into Emacs Lisp, here are
a few considerations before starting that PR:

** TODO Conventions
*** TODO Code style
Doom conforms to [[https://github.com/bbatsov/emacs-lisp-style-guide][@bbatsov's emacs-lisp style guide]] with the following
exceptions:

+ Use ~mapc~ instead of ~seq-do~.
+ No hanging parentheses
+ We use =DEPRECATED= to indicate code that will eventually be removed.

*** Naming conventions
Doom has a number of naming conventions that it uses in addition to the standard
lisp conventions. Third party packages may use their own conventions as well.

**** Lisp Naming Conventions
The lisp conventions are simple. Symbols follow ~NAMESPACE-SYMBOLNAME~ for
public variables/functions (e.g. ~bookmark-default-file~ or
~electric-indent-mode~) and ~NAMESPACE--SYMBOLNAME~ for private ones (e.g.
~byte-compile--lexical-environment~ and ~yas--tables~).

~NAMESPACE~ is usually the name of the containing file or package. E.g. the
~company~ plugin prefixes all its variables/functions with ~company-~.

**** Doom Naming Conventions
+ ~doom/NAME~ or ~+MODULE/NAME~ :: Denotes a public command designed to be used
  interactively, via =M-x= or a keybinding. e.g. ~doom/info~, ~+popup/other~,
 ~+ivy/rg~.
+ ~doom:NAME~ :: A public evil operator, motion or command. e.g. ~+evil:align~,
 ~+ivy:rg~.
+ ~doom-[-]NAME-h~ or ~+MODULE-[-]NAME-h~ :: A non-interactive function meant to
  be used (exclusively) as a hook. e.g. ~+cc-fontify-constants-h~,
 ~+flycheck-buffer-h~.
+ ~doom-[-]NAME-a~ or ~+MODULE-[-]NAME-a~ :: Functions designed to be used as
  advice for other functions. e.g. ~doom-set-jump-a~,
 ~doom--fix-broken-smie-modes-a~, ~+org--babel-lazy-load-library-a~
+ ~doom-[-]NAME-fn~ or ~+MODULE-[-]NAME-fn~ :: Indicates an [[https://en.wikipedia.org/wiki/Strategy_pattern][strategy]] function. A
  good rule of thumb for what makes a strategy function is: is it
  interchangeable? Can it be replaced with another function with a matching
  signature? e.g. ~+lookup-dumb-jump-backend-fn~, ~+magit-display-buffer-fn~,
 ~+workspaces-set-project-action-fn~
+ ~abc!~ :: A public Doom "autodef" function or macro. An autodef should always
  be defined, even if its containing module is disabled (i.e. they will not
  throw a void-function error). The purpose of this is to avoid peppering module
  configs with conditionals or `after!` blocks before using their APIs. They
  should noop if their module is disabled, and should be zero-cost in the case
  their module is disabled.

  Autodefs usually serve to configure Doom or a module. e.g. ~after!~,
 ~set-company-backends!~, ~set-evil-initial-state!~

*** TODO Commits & PRs
+ Target =develop= instead of =master=. The only exception are hotfixes!

*** TODO Keybind conventions

** TODO Your first code contribution

** TODO Submitting pull requests

** TODO Contributing to Doom core

** TODO Contributing to an existing module

** TODO Contributing a new module

* TODO Contributing documentation
Doom Emacs' documentation is an ongoing effort. If you have suggestions,
improvements, tutorials and/or articles to submit, don't hesitate to get in
contact via our [[https://discord.gg/bcZ6P3y][Discord server]] or [[mailto:henrik@lissner.net][email]]. I appreciate any help I can get!

** TODO Contributing to Doom's manual

** TODO Contributing module documentation

* TODO Other ways to support Doom Emacs

* TODO Special thanks