diff --git a/docs/contributing.org b/docs/contributing.org new file mode 100644 index 000000000..66c533d3a --- /dev/null +++ b/docs/contributing.org @@ -0,0 +1,169 @@ +#+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 -f~ 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 = 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 = 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 caffiene 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 + interchangable? 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 diff --git a/docs/index.org b/docs/index.org index c7d19a791..c2b3d18b9 100644 --- a/docs/index.org +++ b/docs/index.org @@ -52,7 +52,14 @@ with = d /=. - [[file:faq.org::Common Issues][Common Issues]] - [[file:faq.org::Contributing][Contributing]] -** TODO Contributing +** TODO [[file:contributing.org][Contributing]] +- [[file:contributing.org::*Where can I help?][Where to get help]] +- Writing an effective bug report +- Suggesting features, keybinds or enhancements +- Contributing code +- Contributing documentation +- Other ways to support Doom Emacs +- Special thanks ** TODO [[file:workflow.org][Workflow Tips, Tricks & Tutorials]]