Skip to content

Latest commit

 

History

History
81 lines (58 loc) · 4.86 KB

developer.org

File metadata and controls

81 lines (58 loc) · 4.86 KB
Raw

Casual Calc Development

Casual Calc 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

Casual Calc 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, Casual Calc uses git.

Given a clone of this repository, ensure that the directory holding casual.el is in your info-path. Add the following lines to your Emacs initialization file.

(require 'casual-calc)
(keymap-set calc-mode-map "C-o" #'casual-calc-tmenu)
(keymap-set calc-alg-map "C-o" #'casual-calc-tmenu)

Branches

For Casual Calc 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 Casual Calc test regression suite is done via Makefile. In the top-level directory of Casual Calc, run this from the command line.

$ make tests

Casual Calc 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 casual-financial.el.

$ make casual-financial.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 casualt-suffix-testbench-runner in tests/casual-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 Casual Calc releases are of high quality.

UX Guidelines

  • Menus must not exceed 80 characters in length.
    • Rationale: Casual Calc follows suit with current Elisp format to conform to the line width of an ADM-3A terminal.
  • Casual Calc UX does not use the Calc inverse or hyperbolic key modifier.
    • Calc functions requiring such modifiers are “flattened” into workflows that obviate them.
      • Example: implement the menu item arcsin instead of inverse sin.
    • Rationale: Calc’s support for inverse and hyperbolic keys is itself an emulation of Hewlett-Packard (HP) calculator behavior which was designed to compensate for its finite number of hardware buttons. As Casual Calc is a software menu user interface, there are no such UX restrictions so it makes no effort to emulate hardware key modifiers. Furthermore, the semantics of inverse and hyperbolic only apply to some functions, but Calc has overused them to support functions where it semantically makes no sense (e.g. inverse calc-fin-fv to get the future value at the beginning of a payment interval). Casual Calc takes the opportunity to cease this practice.
  • Calc commands must be wrapped to include:
    • A docstring describing its behavior and a reference section linking to:
      • a Calc Info page describing the behavior of the wrapped function.
      • a link to the Help of the wrapped command (while not documented, help will provide a link to the source).
    • Rationale: Calc made the decision to implement its own non-standard help system and as such chose to not create docstrings for its functions. This decision unfortunately breaks an assumption made by the Transient help feature which depend on said docstrings for commands associated with a menu item.