* 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=

** Contributing code you did not write yourself

It is fine to propose adding code that you copied from elsewhere,
provided you say where ("provenance") and the license (e.g. "GPL",
"MIT", etc.). Including a URL in a source code comment is ideal.

As a GPL project, we can use code from most other types of licenses,
but we need to know exactly which license, if any.

Also we prefer to give credit ("attribution"), and in fact some
licenses require this.

**Important**: Because it is impossible to know the provenance/license
of code generated by an LLM or "AI" (such as GitHub Copilot) we cannot
accept such code.

** 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.
