Home

Awesome

Contributor guide

This repository has some handy instructions on contributing to my open-source projects.

Linters

Most of my projects include automated linters to improve code quality. Run them locally with make lint. Typically this will do the following:

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.

Documentation

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.

How to write a changelog

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:

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: