1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
* 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.
|
