diff options
| author | Craig Jennings <c@cjennings.net> | 2026-05-05 10:48:02 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-05-05 10:48:02 -0500 |
| commit | 54c7f01dc752ca4bbcc46762cc2ba617cff7411c (patch) | |
| tree | 2fd3472a084812fb28b0bfd4822d6280f690b334 /CONTRIBUTING.md | |
| parent | c099037dd2dfde8cfa2e4c286c8be1fada4277cf (diff) | |
| download | org-drill-54c7f01dc752ca4bbcc46762cc2ba617cff7411c.tar.gz org-drill-54c7f01dc752ca4bbcc46762cc2ba617cff7411c.zip | |
docs: add LICENSE, CONTRIBUTING, CHANGELOG, and NEWS files
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'.
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 87 |
1 files changed, 87 insertions, 0 deletions
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 <https://github.com/cjennings/org-drill/issues> 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-<topic>.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. |
