8.5 KiB
Contributing
- Table of Contents
- Where can I help?
- Reporting issues
- Suggesting features, keybinds and/or enhancements
- Contributing code
- Contributing documentation
- Other ways to support Doom Emacs
- Special thanks
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 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?
- Our issue tracker has many issues. If you find one that you have an answer to, please don't hold back!
- Look for issues tagged good first issue. These were judged to have a low barrier of entry.
- Look for issues tagged 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, file a bug report.
- The 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 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 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 cleanto ensure it isn't. Byte-compilation interferes with debugging! - Run
bin/doom refreshto ensure all plugins are installed and autoload files generated. - Run
bin/doom doctorto diagnose common issues with your system. - Check 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 mto 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). A guide for using the sandbox can be found in the manual. - Make sure your issue hasn't already been reported by searching the issue tracker.
- Make sure your issue hasn't been resolved on the
developbranch of Doom.
If these suggestions haven't worked for you, it's time 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 @bbatsov's emacs-lisp style guide with the following exceptions:
- Use
mapcinstead ofseq-do. - No hanging parentheses
- We use
DEPRECATEDto 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/NAMEor+MODULE/NAME - Denotes a public command designed to be used
interactively, via
M-xor 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-hor+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-aor+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-fnor+MODULE-[-]NAME-fn - Indicates an 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
developinstead ofmaster. 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 Discord server or email. I appreciate any help I can get!