cl-fix: Contributor Guide

Table of Contents

1. Overview

Thank you for showing your interest in contributing to cl-fix! This guide aims to get you up to speed with being an effective contributor.

2. Getting in touch

Email me at z at fix9 dot net.

If it's something that you think might be useful for users to hear, join the mailing list at https://groups.io/g/cl-fix.

3. Key Links

  • Raising bugs: Use the GitLab issue tracker.
  • Requesting features or improvements: Please email the mailing list as a first port of query.

4. Raising a bug

If you're not sure that the behaviour you're encountering is a bug, please check the group to be sure it hasn't been asked.

If you're certain it's a bug, please use the GitLab issues to raise a bug.

Be sure to include:

  • Exact version of the library you're using (Git commit hash works best)
  • Exact VM you're using (SBCL, CCL, etc.)
  • Expected behaviour
  • Actual behaviour
  • Reproduction steps

5. Coding guidelines

In general, follow this guide unless there's a strong reason not to:

https://google.github.io/styleguide/lispguide.xml

Some additional rules that I've been observing:

  • One package per file, and one file per package.
  • For functions that are internal to a package, precede them with %. That is, you should never see other-package::%some-fn (except maybe in tests).
  • Always run the tests! I don't (yet) have a public CI/CD set up. Currently I'm only testing on sbcl and ccl (see ./test.sh and ./test-ccl.sh) on Linux x8664.
  • The master branch is what pulled from quicklisp, so it must remain pristine.
  • Anything in the 'hot loop' should, ideally, never perform an generic function call. There's a performance overhead here that we should avoid if we can.
    • The 'hot loop', as I'm calling it, is anything on the critical path to receiving and responding to a message.
    • Generic function calls are however fine for set-up code and lifecycle code that isn't run as frequently.

I'm not exactly getting a barrage of pull requests at the moment, so I'll add more structure here as necessary. I'm also keen to learn from contributors, so if there are any obvious areas of improvement please feel free to shout out to me or raise a PR.