Contribute¶
Contributions are very welcome. Development is done in the GitHub repository. If you find a bug, please report it in the issue tracker.
Pull requests¶
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.
Tests¶
Cask is used for testing. The tests are written using the Emacs built in ERT framework and executed with ert runner. There are also compilation tests, style check, package verification etc.
Setup¶
Install all developer dependencies:
make deps
Running¶
Run the whole test suite:
make test
Run only the unit/integration tests:
make ert-test
Manually test the package with Emacs:
cask emacs -Q -L . --eval="(progn (require 'rg) (enable-default-bindings))"
Documentation¶
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 ReadTheDocs documentation is generated after committing to the main repository but the info manual needs to be created locally and submitted as part of a documentation patch. It’s advisable to build both locally and verify the output to make sure the changes looks OK.
Setup¶
-
apt-get install python3-sphinx
Building¶
HTML documentation
make html
Open
docs/rst/_build/html/index.html
in a browser.Info documentation
make info
To view in emacs:
C-u M-x info [RET]
Then select the
docs/rst/_build/info/rgel.info
file.
Create a patch¶
Edit the org files in
docs
directory.When everything looks good in both HTML and info.
make info
Commit both the changed org files and info file.
Push and create PR.