Skip to content

Latest commit

 

History

History
140 lines (93 loc) · 4.1 KB

CONTRIBUTING.org

File metadata and controls

140 lines (93 loc) · 4.1 KB
Raw

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:

;; Package-Requires: ((emacs "25.1"))

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:

(add-to-list 'load-path "/path/to/the/git-clone/dir")
(require 'racket-mode)

If you use use-package, you can simply replace

(use-package racket-mode
  :ensure t)

with

(use-package racket-mode
  :load-path "/path/to/the/git-clone/dir")

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.