Gerbil is a growing open source project, your contributions are welcome and appreciated!
To get started contributing to Gerbil, follow the Installation Guide to acquire the source code, install dependencies, and compile the system. You'll need git.
You may also install Gerbil from your package manager of choice, but the source code and dependencies to modify and later test changes are still required.
Gerbil development is manged using GitHub and pull requests (or "PRs") are the primary way to submit changes. Start by forking the repository, make your changes, then submit a pull request.
If you don't wish to use GitHub, patches may be accepted via the gerbil-users mailing list as well.
When working directly on the mighty-gerbils/gerbil repo (or others in the
mighty-gerbils namespace), please follow the following conventions for naming
branches:
- use a
doc-prefix for documentation changes (ex.doc-contributing) - use a
feat-prefix for new features (ex.feat-lsp) - use a
bug-prefix for bug fixes (ex.bug-compile-error-on-uninitialized-value - use a
core-prefix for core compiler changes (ex.core-union-types)
Documentation work is a fantastic way to get started with contributing to Gerbil! If you
don't know where to start, there may be issues marked with the documentation
label
that could be a good place to look. As of now, there are many areas of the Gerbil
codebase that do not have adequate documentation. The Gerbil Core team is actively
working to improve this, but help is always appreciated.
Documentation generally lives on the projects main site, cons.io.
Code documentation is stored in the doc/
folder as markdown. If you're
unfamiliar with Markdown, the Markdown Guide is a
helpful reference. We use VuePress to process the
markdown into HTML, follow their guide
for additional information. Of most interest is likely the Markdown
Extensions section.
Gerbil's documentation has 3 main sections, Guide, Tutorials, and Reference.
Guides are stored under doc/guide and should cover topics that a reader will want to
follow to achieve some goal.
Examples of this are the Installation Guide, Getting Started with Gerbil Development, and Gerbil on MacOS.
Tutorials are stored under doc/tutorials and focus on providing learning-oriented
examples that hackers new to Gerbil can use to get familiar with the ins-and-outs of the
language and standard library.
Some examples include the Key-Value Store Server and Web programming with the Gerbil HTTP server.
Reference documentation is stored in in doc/reference and further subdivided into
dev/, gerbil/, srfi/, and std/. Reference material contains descriptions of
systems, functions, and syntax used within the Gerbil language.
The dev folder contains reference material for use in the development process using
Gerbil. It includes topics such as
Testing and
Debugging Gerbil code.
gerbil/ contains documentation on the core Gerbil language. This includes the core
prelude, runtime, and expander.
srfi/ largely provides an index for supported Scheme Requests for
Implementation or "SRFIs" that are implemented or
re-exported by Gerbil.
Finally, std/ contains references for the Gerbil Standard Library. This folder's
substructure mirrors the module structure of the standard library closely. Most new
modules, syntax, and functions should be documented here.
To preview changes, a JavaScript runtime is necessary. NodeJS is a good place to start, but other options may work.
Preview changes to doc/ with the following commands, run from within doc/:
npm install
npm run devThis will setup the dependencies and run a development server on port 8080. Access it
at http://localhost:8080.
We don't quite yet have a fixed style for Gerbil docs, but please try to remain consistent with other docs in a similar category.
Gerbil aims to have an extensive "batteries included" standard library. That being said, not every new feature/module may get included. If there are questions, please reach out in the Matrix room or mailing list for guidance or feedback. Most often, if a module or package is decided to not be included in the stdlib, it will be added to the directory instead. Do not let this discourage from making contributions! The Gerbil ecosystem benefits greatly from community library support!
Contributions to the standard library should always be accompanied with corresponding documentation. Pull requests that do not include documentation may not be approved and merged.
The standard library is located under src/std.
The :std/make build tool is used to compile the standard library, therefore new
modules must be included in the top level
build-spec.ss
for the stdlib, located at src/std/build-spec.ss.
Modules that provide types and an interface generally follow the following convention:
Source files for the module are stored in a folder with the intended name for the
module. A file is created at the same level as the folder with the same name with the
.ss suffix. This file is responsible for importing and re-exporting the API and/or
interfaces of the module.
Interfaces that are exported by a module are defined in a interface.ss file.
Public API symbols are defined in an api.ss.
Other source files may exist in this folder at the authors discretion, but should generally not be imported by other modules.
An example of this structure can be observed with the S3 module:
- Module reexport:
s3.ss - API:
api.ss - Interface:
interface.ss
New code should be tested to the best extent possible. Tests for a particular file
should live next to that file with a -test suffix applied to the name. If a test
covers an entire module, the module name with the -test suffix should be used instead.
For example, tests covering the :std/net/websocket module live in
src/std/net/websocket/websocket-test.ss and the tests for
src/std/net/websocket/socket.ss live in src/std/net/websocket/socket-test.ss.
Executing tests on the standard library is slightly different than in other modules, as it is not possible use a local tree directly. The process is documented in the Hacking on the Standard Library guide.
To execute all tests before submitting a pr, run make check from the root of the
repository. Alternatively, ./build.sh env gerbil test ./... may be used.
Gerbil code generally uses 2-space indents, though the syntax is very flexible. There is no formalized style guide (yet), but do try to follow the style of other code in the project whenever possible.
Gerbil's bootstrapping process is documented here. Contributions to the core are welcome, but may be subject to more scrutiny than other changes: it's the heart of Gerbil after all.
Changes to the core prelude, runtime, compiler, or expander require rebootstrapping. The process (and a lot of context and background) is documented in The Gerbil Bootstrap.
Gerbil's core lives in src/gerbil.