Skip to content

Latest commit

 

History

History
67 lines (44 loc) · 3.07 KB

developer.org

File metadata and controls

67 lines (44 loc) · 3.07 KB

Causal Development

Causal is an open source project and as such is always open for contributors to its development.

This document provides guidance on how to contribute to its development from a programming perspective.

Development Environment

Causal is developed primarily using a GNU toolchain. GNU tools required are:

  • make
  • awk
  • grep
  • bash

Also needed is the Python semver module. This will require an installation of Python 3.x, ideally at 3.9 or higher.

For source code management, Causal uses git.

Given a clone of this repository, ensure that the directory holding causal.el is in your info-path.

Branches

For Causal development, there are two git branches of note:

  • main for releases to the general public.
  • development for staging of stable pre-release functionality.

Planned changes for the next release are done on feature branches that are merged via pull request into development. Upon QA of development, those changes are merged to main for release to the general public.

Test Regression

Running the Causal test regression suite is done via Makefile. In the top-level directory of Causal, run this from the command line.

$ make tests

Causal uses the ERT framework to compose and manage tests.

One can run a test for a single file by using a “phony” target with a suffix of .elt in the lisp/ directory containing all the source files.

For example, in the lisp/ directory, run this command to exercise all tests for functions in causal-version.el.

$ make causal-version.elt

External Pull Requests

Before you submit a pull request (PR):

  • If it is a new feature, please propose an enhancement issue instead.
    • Your enhancement issue should be in the form of a products requirement document (PRD).
    • PRs without an approved PRD associated with it will be summarily rejected.
    • Contributing to code development for a PRD requires advance approval from the maintainer. PRs submitted outside of this flow will be rejected.
  • PRs must pass the test regression suite.
    • New behavior introduced in a PR should have unit tests associated with it.
      • Typically this entails exercising all items in a Transient menu. Look at usage of causalt-suffix-testbench-runner in causal-lib-test-utils.el to see how this is done.
  • PRs must be made against the development branch on GitHub.
    • If the pull request is made against main but can be re-targeted to development, it will be reviewed.
    • A pull request with merge conflicts to development will be summarily rejected.

All of the above is intended to ensure that Causal releases are of high quality.

UX Guidelines

  • Menus must not exceed 80 characters in length.
    • Rationale: Causal follows suit with current Elisp format to conform to the line width of an ADM-3A terminal.