* Reporting bugs

If you're going to report a bug --- thank you!

Please use =M-x racket-bug-report= to generate a buffer with
information that will help to reproduce and understand the bug:

- Emacs version.
- Value of important Racket Mode variables.
- Minor modes that are active.

Please copy that and paste in your bug report.

* Making pull requests

If you'd like to make a pull request --- thank you!

Here is some information to help you.

** Package dependencies

For end users, Racket Mode currently has zero dependencies on other
packages --- in =racket-mode.el= =Package-Requires:= is just:

#+BEGIN_SRC elisp
;; Package-Requires: ((emacs "25.1"))
#+END_SRC

For hacking on Racket Mode and to run tests, a couple packages are
required. To install them: =make deps=.

The recent trend has been for Racket Mode to depend on fewer packages,
not more. For example =dash.el= and =s.el= were dropped in favor of
directly using the built-in Emacs functions wrapped by those packages.

Having said that, if your PR proposes adding a dependency on a new
package that you think is worthwhile, please make sure your PR updates
both:

1. the =Package-Requires:= line in =racket-mode.el=
2. the =deps= target in =Makefile=

** Pointing Emacs to your Git clone

After installing dependencies you should just need to add the path to
your local clone of Racket Mode to =load-path= and require it:

#+BEGIN_SRC elisp
(add-to-list 'load-path "/path/to/the/git-clone/dir")
(require 'racket-mode)
#+END_SRC

If you use =use-package=, you can simply replace

#+BEGIN_SRC elisp
(use-package racket-mode
  :ensure t)
#+END_SRC

with

#+BEGIN_SRC elisp
(use-package racket-mode
  :load-path "/path/to/the/git-clone/dir")
#+END_SRC

If you have previously been using Racket Mode as a package installed
from MELPA, you might want to remove that, at least for the duration
of your hacking:

- =M-x package-delete= and enter =racket-mode=.
- Restart Emacs.

** Generating reference documentation

We generate reference documentation from doc strings for commands,
variables, and faces.

- If you add a brand-new command =defun=, =defcustom=, or =defface=,
  please also add it to the appropriate list in =doc/generate.el=.

- Whenever you edit a doc string for a command =defun=, =defcustom=,
  or =defface=, please =cd doc && make clean docs=, and commit the
  updated files.

** Tests

Currently tests are on the light side. More are welcome.

Please do run =make test= locally to ensure your changes pass the
existing tests.

GitHub Actions also does =make test= automatically on your pull
request.

GitHub branch protection is enabled for the main branch --- merges
are blocked until tests pass.

*** Example files for indentation and font-lock

Some Racket Mode tests apply indentation and font-lock to the
=test/example/example.rkt= and =test/example/indent.rkt= files and
compare the result to corresponding =.faceup= files (generated by the
=faceup= package).

As a result, if your PR intentionally modifies indentation or
font-lock, you may need to regenerate the =.faceup= files. To do so:

1. Disable any personal Emacs features that affect font-lock or
   indentation. For example you may need to =M-x global-paren-mode=
   and =M-x prettify-symbols-mode= to disable those.

2. For each =.rkt= file:

    - Visit the =.rkt= file.

    - =M-x mark-buffer= and =M-x indent-region=.

    - =M-x save-buffer= to save the =.rkt= file.

    - =M-x faceup-write-file= and answer, yes, replace the existing
      =.faceup= file.

3. Re-enable any personal features you disabled in step 1.
