doomemacs/docs/contributing.org

#+TITLE: Contributing
#+STARTUP: nofold

Doom Emacs is an active and ongoing project, maintained mostly by a single
person, but includes the efforts of 200 contributors and growing. There is no
shortage of things that need doing; bugs that need stomping, features that need
implementing, and documentation that needs documenting. If Doom's been useful to
you, convert some caffiene into code; it'd be a huge help!

You are welcome to [[https://discord.gg/64QNqtq][join us on our Discord server]], otherwise read on to learn how
to contribute to our fine corner of the interwebs.

* 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