c363791da0
-f is necessary when there are changes to your system that Doom needs to pick up when running 'doom refresh'. It won't do anything if your doom dotfiles haven't visibly changed, which won't be the case if you are installing, say, mu4e or vterm, through your system package manager. What was initially a time-saving mechanic has become a trap for beginners, so I've made -f its default behavior and its previous behavior opt-in with the -n / --if-necessary switches.
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
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?
- 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!