This repository has some handy instructions on contributing to my open-source projects.
Most of my projects include automated linters to improve code quality.
Run them locally with make lint
. Typically this will do the
following:
- Check for no byte-compiler warnings.
- Run Checkdoc.
- Check for no lines longer than 79 characters. Why 79?
- Check that the code is indented correctly.
- Update the table of contents in the README. Please install markdown-toc for this to work!
The linters are run automatically against your pull request by CircleCI. All pull requests must pass CI before being merged.
One reason the CI can fail even though make lint
worked for you is
that your code doesn't work in an older version of Emacs. CircleCI
runs the linters against every supported version of Emacs. You can do
the same by installing Docker and running
make docker VERSION=25.3
(or equivalently for whatever version is of
interest). That will put you in a shell with the project source code
and all dependencies automatically installed in a sandbox.
We write documentation. Every symbol, public or private, needs a
docstring which is enough to fully understand the behavior without
inspecting the source code. Every public symbol (the ones without --
in their name) needs furthermore to be explained in the README.
We also write changelogs. The changelog is kept in CHANGELOG.md
.
The idea of the changelog is to document user-visible changes to the project in a user-readable way (unlike the commit history, which is much more detailed and hard to read).
Here is a changelog in progress:
## Unreleased
### Enhancements
* In `read-file-name`, when a default is provided (for example in the
`dired-do-rename` command), we actually use it as the initial
contents of the minibuffer, which allows you to have convenient
access to the default filename when that default file does not exist
([#25]).
* We now bind `minibuffer-completing-file-name` during
`read-file-name`, in conformance with the standard Emacs interface
([#30]).
## Bugs fixed
* You can now use the undo system in the minibuffer. Previously,
trying to do so would break Selectrum ([#31]).
[#25]: https://github.com/raxod502/selectrum/pull/25
[#30]: https://github.com/raxod502/selectrum/issues/30
[#31]: https://github.com/raxod502/selectrum/issues/31
Notice:
- There's a section called
Unreleased
where all the info goes. When I make a release, I relabel the section with the name of the release and copy it into the GitHub release. After the release, we add in a newUnreleased
section at the top. - We have sub-sections for the different types of changes. There
aren't any strict rules about which sub-sections should be used, but
here are some suggestions:
Breaking changes
,Added
,Enhancements
,Deprecated
,Removed
,Bugs fixed
,Performance
. - Each change goes in a new bullet point, and includes a link to the
relevant issue(s) or pull request(s) in parentheses. The link
anchors go at the bottom of the
Unreleased
section, in alphabetical order.
What to include in the changelog: Any user-visible changes since the last release. Changes to the implementation of an internal function don't qualify, unless they fix a bug or improve performance significantly. Also, if you fix a bug that was introduced since the last release, there's no need to document that. The audience of a changelog should be assumed to be running the last release.
Example changelogs: