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.
170 lines
8.5 KiB
Org Mode
170 lines
8.5 KiB
Org Mode
#+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
|