3 Contributing to Racket Development
The Racket developers are happy to receive bug reports and improvements to the implementation and documentation through GitHub issues and pull requests:
Issues (bug reports): https://github.com/racket/racket/issues
Pull requests (improvements): https://github.com/racket/racket/pulls
The Racket distribution includes scores of packages that have their own separate repositories, which somewhat complicates the process of sending pull requests. The mechanism is the same, but see Distribution-Package Contributions for more guidance.
By making a contribution, you are agreeing that your contribution is licensed under the LGPLv3, Apache 2.0, and MIT licenses. Those licenses are available in the Racket Git repository in the files "LICENSE.txt", "LICENSE-APACHE.txt", and "LICENSE-MIT.txt".
3.1 Main-Repository Contributions
The main Racket Git repository contains the implementation of everything that is in the Minimal Racket distribution. That includes the runtime system, core libraries, and raco pkg so that other packages can be installed.
The main Racket repository also has the source to the Racket Reference, Racket Guide, and other core-ish documentation, including the source to the document that you are reading. Those document sources are in the repository’s "pkgs" directory.
Finally, the main repository includes a few other packages that are especially tightly bound to the runtime-system implementation, such as the "compiler-lib" package or the "racket-test" package. Those package sources are also in the repository’s "pkgs" directory.
To develop improvements to any of those parts of Racket, following the usual GitHub-based workflow:
Fork the Racket repository.
Create an in-place build as described in Building Racket from Source.
Make your changes and rebuild with make or make as-is or raco setup, where raco setup is the best choice when modifying Racket libraries that are in "collects" or a package. If your changes involve modifying things that are part of the racket executable, then a simple make may not suffice; see “Modifying Racket” in "racket/src/README.txt" for more information.
Commit changes to your fork and submit a pull request.
See the General Contribution Guidelines.
3.2 Distribution-Package Contributions
If you find yourself changing a file that is in a "share/pkgs" subdirectory (either installed as part of a Racket release or as a product of an in-place build), then that file is probably not part of the main Racket Git repository. It almost certainly has its own Git repository somewhere else, possibly within https://github.com/racket, but possibly in another user’s space. The name of the directory in "share/pkgs" is almost certainly the package name.
To start working on a package ‹pkg-name›, in the directory you’d like to hold the package’s source, use
raco pkg update --clone ‹pkg-name›
For Racket version 8.14 and earlier as a release or snapshot, before using --clone, you first need to adjust the package installation to use the source specified by the main package catalog:
raco pkg update --no-setup --catalog https://pkgs.racket-lang.org ‹pkg-name›
That command will clone the package’s source Git repository into "‹pkg-name›" within the current directory and checkout the appropriate commit. Then, it will replace the current installation of the package in your Racket build to point at that directory, and then it will rebuild (essentially by using raco setup) with the new location of the package installation. Now you can edit in "‹pkg-name›", and your changes will be live.
Some information that might improve your experience:
You can add --no-setup to the raco pkg update command to skip the raco setup step, which makes sense if you want to make changes and then run raco setup yourself.
The argument after --clone is a directory, and by default, the package name is inferred from the directory. Within an in-place build of the main Racket repository, for example, the conventional use
raco pkg update --clone extra-pkgs/‹pkg-name›
creates "extra-pkgs/‹pkg-name›" as a clone of the Git repository for ‹pkg-name› (and ".gitignore" for the Racket repository excludes "extra-pkgs").
To use a clone directory name that is different than the package name, you can supply the package name explicitly after the --clone directory name:
raco pkg update --clone ‹repo-name› ‹pkg-name›
If you’re done and want to go back to the normal installation for ‹pkg-name›, use
raco pkg update --unclone ‹pkg-name›
See Developing Packages with Git for more information about how packages are meant to work as Git repositories.
Note that none of this is necessary if you’re modifying a package in the main Racket repository’s "pkgs" directory. Those are automatically linked in place for an in-place build of Racket.
3.3 General Contribution Guidelines
When you make a pull request, the Racket developers will help you get the improvement in shape to merge to the Racket repository. You can make that process faster by keeping a few guidelines in mind:
Try to follow the style guide.
When you fix a bug or create a new feature, include a test case for it.
Note that core Racket tests are in "pkgs/racket-test-core/tests/racket", and tests for other libraries are also sometimes in a separate "-test" package.
Include new or updated documentation as appropriate.
To locate a documentation (Scribble) source file, visit the current documentation in a browser, and click at the page heading. A box will appear with a URL to a documentation source. Note that while it is likely that the documentation source will not be the file that you want to edit exactly, it should give you a rough idea for where it is. Particularly, the Racket reference is in "pkgs/racket-doc/scribblings/reference", and the Racket guide is in "pkgs/racket-doc/scribblings/guide".
When adding to a library or extending an existing binding’s behavior, be sure to include a history note in the documentation to record the change.
Build with your changes.
Don’t break the Racket build. That means at least checking that raco setup runs and completes without errors. If you added or modified documentation, visually inspect the newly rendered documentation to make sure it reads as intended.
A common mistake is to just run a modified library or its tests, but where a change creates a new package dependency that will only be detected by a full raco setup. Really: run raco setup.
For changes to the C code, ensure your code follows the C99 standard.
On Unix systems, extensions that are part of the _DEFAULT_SOURCE pre-processor flag are also allowed. See the glibc manual for more details.
3.4 More Resources
For additional pointers on how to contribute to Racket, see
https://github.com/racket/racket/wiki/Ways-to-contribute-to-Racket