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.
Commit changes to your fork and submit a pull request.
See the General Contribution Guidelines.
The variant of Chez Scheme that is needed to build Racket on Chez Scheme has its own repository (to preserve the shape of the original Chez Scheme reporitory): https://github.com/racket/ChezScheme.
3.2 Distribution-Package Contributions
If you find yourself changing a file that is in a "share/pkgs" subdirectory, then that file is 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›, it’s usually best to go to the root directory of your Racket repository checkout and run
raco pkg update --clone extra-pkgs/‹pkg-name›
That will create "extra-pkgs/‹pkg-name›" as a clone of the package’s source Git repository, 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 "extra-pkgs/‹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.
A package is sometimes a subdirectory within a Git repository, and it would be better if the checkout in "extra-pkgs" matched the repository name instead of the package name. If you know the repository name, you can use
raco pkg update --clone extra-pkgs/‹repo-name› ‹pkg-name›
to make the distinction.
This same approach will generally work if you’re starting from a distribution installer instead of the checkout of the Racket sources from the main Git repository. You’ll need write permission to the installation, though, so that raco pkg update can redirect the package. Also, there’s no particular reason to use extra-pkgs in that case.
If you’re done and want to go back to the normal installation for ‹pkg-name›, use
raco pkg update --catalog ‹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.
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