If you want to submit a patch, please submit a GitHub pull request. If you want to submit any larger code changes, please create an issue first for discussion. Some features does not fit well into this package and there is also good to agree on the general design before doing any major work.
The minimum requirements for a pull request to be accepted is that all existing tests pass and test coverage should not decrease. Often a patch also needs additional tests, new/changed documentation etc.
Don’t strive to submit a perfect pull request directly. It’s often better to submit something simple that shows the main direction of the new code in order to discuss the best way to proceed and what additions are needed.
Docker can be used to run the tests or generate documentation locally without installing dependencies on the host and to test with different emacs versions.
To use docker, just set the
USE_DOCKER variable when
running the tests.
EMACS_VERSION variable can be used to select emacs
version. Note that dash (‘-’) is used instead of points (‘.’) in the
version numbering. So emacs 28.2 is specified as
Emacs are installed from https://github.com/purcell/nix-emacs-ci so
only emacs versions supported in that repository will work.
Build docker container:
# Don't use the USE_DOCKER variable here make EMACS_VERSION=26-2 docker-build
To run all the tests in docker image:
make USE_DOCKER=true test
Use a specific emacs version:
make USE_DOCKER=true EMACS_VERSION=snapshot
Generate html documentation:
make USE_DOCKER=true html
Cask is used for testing. The tests are written using the Emacs built in ERT framework and follows the conventions of ert runner although ert_runner is no longer used. There are also compilation tests, style check, package verification etc.
Install all developer dependencies:
Run the whole test suite:
Run only the unit/integration tests:
Manually test the package with Emacs:
cask emacs -Q -L . --eval="(progn (require 'rg) (enable-default-bindings))"
The documentation is written in org mode. The export target is restructured text suitable for the Sphinx documentation generator. Sphinx is used to export the output from org mode to info and HTML documentation. The resulting .rst files are used for the online documentation on https://readthedocs.io.
The end user documentation is generated after committing to the main repository. It’s advisable to build both html and info documentation locally and verify the output to make sure the changes looks as expected.
sudo apt install python3-sphinx python3-sphinx-rtd-theme
sudo apt install texinfo
docs/rst/_build/html/index.htmlin a browser.
To view in emacs:
C-u M-x info [RET]
Then select the