Contributing to ThreadButler

Documentation

General

The public API of any module must have doc comments.

Private procs that are used to build a NimNode (e.g. a proc or a type) should have doc comments, even if only for maintainers.

Wording

Words are important. Introducing new terms with specific meaning therefore should come together with an explanation for it in the Glossary.

Also try to limit terms used to those in the glossary for consistency.

Changes to procs inferring names from ThreadName

Many identifiers are inferred from a given ThreadName that the user provides via macro. The procs that are the central points for these operations are at the start of codegen.

If the output of one of these procs is changed, then also check the doc comments of every proc using it as well, as they might now require updating. Also update generatedCodeDocs.nim.

Features

Consider whether a new given feature might benefit from being provided as an example. Examples are part of the test-suite as well as acting as documentation and thus will enable better stability.

When adding an Example, also add it to the nimibook examples page

Compiler Flags

When contributing code that introduces new compiler flags, make sure they are mentioned and explained in the nimibook docs page on flags

Compiler flags are typically prefixed with butler.

Generated Code

When contributing features that generate new code, make sure that they are mentioned and documented in the nimibook docs page for generated code

Coding Style

General

This project uses camelCase.

Contants are written using SCREAMING_CASE.

Macros

This project aggressively validates every step of the way that NimNodes have their anticipated NimNodeKinds.

If a proc acting on NimNodes or a macro requires NimNodes to be of a certain kind, use expectKind (for macros) and assertKind (for procs). The goal is to figure out as early as possible if nodes are not behaving as expected, which makes macro-debugging easier and allows for better error messages.

When using expectKind, please provide actionable user-facing error messages.