From 54c7f01dc752ca4bbcc46762cc2ba617cff7411c Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Tue, 5 May 2026 10:48:02 -0500 Subject: docs: add LICENSE, CONTRIBUTING, CHANGELOG, and NEWS files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four new top-level docs to round out the project's public-facing materials: - LICENSE: full GPL-3 text, mirroring the header notice in org-drill.el (copied from emacs-wttrin's bundled license). - CONTRIBUTING.md: bug-reporting guide, patch flow (fork → branch → tests → PR), development setup instructions wrapping the existing make targets, and testing/style notes pointing at the TDD discipline expected. - CHANGELOG.md: keepachangelog format with an Unreleased section documenting every change since the fork — bug fixes by issue number, new infrastructure (CI, coverage, lint), structural refactors, and removals. - NEWS: shorter user-facing summary highlighting the bugs most likely to have bitten existing users. Closes the [#A] TODO 'Add CONTRIBUTING, CHANGELOG, NEWS, and a standalone LICENSE file'. --- CONTRIBUTING.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 CONTRIBUTING.md (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e43e59d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,87 @@ +# Contributing to org-drill + +Thanks for your interest. This is a small project; the contribution flow is informal. + +## Reporting a bug + +Open an issue at with: + +- The behavior you expected vs. what you saw +- A minimal `:drill:`-tagged Org snippet that reproduces it (if applicable) +- Your Emacs version (`M-x emacs-version`) and Org version (`M-x org-version`) +- Anything in `*Messages*` that looks related + +If you have a stack trace, paste the full backtrace inside a fenced code block. + +## Sending a patch + +1. Fork the repo and branch from `main`. +2. Write or update tests for whatever you're changing — see [Testing](#testing) below. +3. Run `make test-unit` and `make compile` and confirm they pass. +4. Open a PR. Conventional-commits-style commit messages are appreciated (`fix:`, `feat:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`); see the existing `git log` for examples. + +CI will run the test matrix (Emacs 28.2, 29.4, snapshot), `make lint` (informational), `make compile`, and `make coverage` against your branch. + +## Development setup + +Requires [Cask](https://github.com/cask/cask) and Emacs 25.3+ with Org 9.6+ available. + +```sh +# Install dependencies into a project-local .cask/ directory +make setup + +# Run the unit-test suite +make test-unit + +# Run a single test file +make test-file FILE=test-org-drill-entry-empty-p.el + +# Run tests matching a name pattern +make test-name TEST='*scheduler*' + +# Generate a coverage report (writes .coverage/simplecov.json) +make coverage + +# Byte-compile org-drill.el (informational warnings) +make compile + +# Run checkdoc + package-lint + elisp-lint (informational) +make lint + +# Quick parens sanity check +make validate-parens + +# List every available target +make help +``` + +## Testing + +The project uses [ERT](https://www.gnu.org/software/emacs/manual/html_node/ert/) for unit tests. Tests live under `tests/` as `test-.el` files. + +When adding new code: + +- **Write a failing test first**, then implement until green. This isn't optional — `make coverage` is currently around 78%, and we want to keep it climbing. +- For each new public function, cover three categories: normal cases (happy path), boundary cases (edge values, empty inputs, max/min), and error cases (invalid inputs, missing required state). +- Mock at external boundaries (`current-time`, `read-key-sequence`, `read-string`, `org-id-get-create`). Don't mock internal helpers. +- Slow tests (multi-second integration scenarios) should be tagged `:tags '(:slow)` so they're excluded from the default `make test-unit` runner. + +When fixing a bug: + +- Write a regression test that reproduces the bug **before** changing the implementation. +- Verify the test fails on the unfixed code. +- Apply the fix and verify the test passes. +- Mention the upstream issue number in the commit message when applicable. + +The `robot/` directory contains end-to-end UI tests that drive a real Emacs frame via window-system key events. They require X11 and aren't part of `make test-unit`. Run them with `make robot` (or `make robot-all` for the full set) only on a graphical session. + +## Style notes + +- Lisp code should byte-compile cleanly with `make compile`. Existing source has known docstring debt that `make lint` will surface; new code should not add to it. +- Function and variable names are `kebab-case` and prefixed with `org-drill-` (or `org-drill--` for internal). +- Use `defcustom` for user-configurable settings, with a clear `:type` and a `:group` of `org-drill`. +- Prefer `cl-letf`, `let`, and `unwind-protect` over global state mutation. Where global state is unavoidable (session objects, persisted matrices), keep its lifecycle explicit. + +## License + +By contributing you agree that your contributions are licensed under the same GPL-3.0-or-later as the rest of the project. -- cgit v1.2.3