Contributor’s Guide

Thank you very much for your interest in contributing to Flycheck! We’d like to warmly welcome you in the Flycheck community, and hope that you enjoy your time with us!

There are many ways to contribute to Flycheck, and we appreciate all of them. We hope that this document helps you to contribute. If you have questions, please ask on our issue tracker or in our Gitter chatroom.

For a gentle start please take a look at all the things we need your help with and look for beginner-friendly tasks.

Please note that all contributors are expected to follow our Code of Conduct.

Bug reports

Bugs are a sad reality in software, but we strive to have as few as possible in Flycheck. Please liberally report any bugs you find. If you are not sure whether something is a bug or not, please report anyway.

If you have the chance and time please search existing issues, as it’s possible that someone else already reported your issue. Of course, this doesn’t always work, and sometimes it’s very hard to know what to search for, so this is absolutely optional. We definitely don’t mind duplicates, please report liberally.

To open an issue simply fill out the issue form. To help us fix the issue, include as much information as possible. When in doubt, better include too much than too little. Here’s a list of facts that are important:

  • What you did, and what you expected to happen instead

  • Whether and how you were able to reproduce the issue in emacs -Q

  • Your Flycheck setup from M-x flycheck-verify-setup

Windows-only issues

As Flycheck does not support Windows officially we generally do not attempt to fix issues that only occur on Windows. We will move all Windows-only issues to the list of open Windows issues, and leave them to Windows users and developers.

We welcome anyone who wants to fix open Windows issues, and we will merge pull requests for improved Windows compatibility. If you know Windows and Emacs, please take a look at the list of open Windows issues and try to fix any of these.

Feature requests

To request a new feature please open a new issue through our issue form. A feature request needs to find a core developer or maintainer who adopts and implements it.

The build system

Flycheck provides a Makefile with some convenient targets to compile and test Flycheck. The Makefile requires Cask, the Emacs Lisp dependency manager. Run make help to see a list of all available targets. Some common ones are:

  • make init initialises the project by installing local Emacs Lisp dependencies.

  • make check checks all Emacs Lisp sources. This target requires Emacs 25.

  • make compile compiles Flycheck and its libraries to byte code.

  • make format formats all Emacs Lisp sources.

  • make specs runs all Buttercup specs for Flycheck. Set PATTERN to run only specs matching a specific regular expression, e.g. make PATTERN='^Mode Line' specs to run only tests for the mode line.

  • make unit runs all ERT unit tests for Flycheck. We are phasing ERT out in favour of Buttercup; no new ERT unit tests will be added and this target will eventually be removed.

  • make integ runs all integration tests for Flycheck syntax checkers. These tests are dependent on the checker programs and their versions; expect failures when running this target with bleeding-edge checkers. Set SELECTOR to run only tests matching a specific ERT selector, e.g. make SELECTOR='(language haskell)' integ to run only integration tests for Haskell. make LANGUAGE=haskell integ is a shortcut for this.

    If you want to replicate the integration tests that are run on the CI, continue reading.

Running all the integration tests

To run all the integration tests, you need to have all the syntax checkers installed. As that can be tedious work, and since your locally installed tools can have different versions than the tools used on the CI, we have created a Docker image with most of the supported checkers. To use the Docker image locally and replicate the integration tests that are run on the CI, first you need to build the image:

cd flycheck
docker pull flycheck/emacs-cask:26.2
docker pull flycheck/all-tools:latest
docker build --build-arg EMACS_VERSION=26.2 --tag tools-and-emacs:26.2 -f .travis/tools-and-emacs .

Replace 26.2 by the Emacs version you want to test. See the available versions on docker hub.

Once the image is built, you can use it to run the integration tests:

docker run --rm -it -v `pwd`:/flycheck --workdir /flycheck tools-and-emacs:26.2 /bin/bash -c "make integ"

Note that the all-tools image is rebuilt each month, so the versions of the its syntax checkers will change accordingly. You can check the version of each installed tool by running the check-tools script in the image:

docker run --rm -it -v `pwd`:/flycheck --workdir /flycheck tools-and-emacs:26.2 check-tools

Pull requests

Pull Requests are the primary mechanism to submit your own changes to Flycheck. Github provides great documentation about Pull Requests.

Please make your pull requests against the master branch.

Use make check specs unit to test your pull request locally. When making changes to syntax checkers of a specific language, it’s also a good idea to run make LANGUAGE=language integ and check whether the tests for the particular language still work. A successful make integ is by no means mandatory for pull requests, though, the continuous integration will test your changes, too.

Important

To contribute to Flycheck you must sign our CLA (Contributor License Agreement). The CLA Assistant bot will automatically ask you to do this when you open a pull request, and will let you sign the CLA through your Github account.

We require this process mostly to make you aware of the licensing implications of contributing to Flycheck and to obtain your explicit approval of our licenses for your contribution.

All pull requests go through a two-stage review process:

  • Maintainer review the general idea and direction of the pull request and leave a LGTM comment if they believe that the change is a good addition to Flycheck. We currently require at least one approval from a maintainer.

  • All contributors—language teams in particular—check the technical implementation of a pull request through pull request reviews, and either approve it or request changes. We currently require at least one approval and no requested changes.

Important

We have a comprehensive Style Guide that explains what features we will accept, how our code should look likewise, what tests we require, how commit messages should look like, and so on.

Take a look at it to see what we look for in a code review.

Additionally all pull requests go through automated tests on Travis CI which check code style, run unit tests, etc

Feel free to mention individual contributors or entire teams (e.g. @flycheck/maintainers or @flycheck/javascript) to ask for help or feedback or request a review. Please mention the maintainers (@flycheck/maintainers) if you think that your pull request has been waiting for review too long. You can expect a first response to any pull request in a couple of days.

Once the pull request passed review and automated tests we will merge it. We may also ask you whether you’d like to join Flycheck and help us, thus giving you commit access to our repository and let you merge your own pull request.

Writing documentation

Documentation improvements are very welcome. Flycheck’s manual is written in reStructuredText and built with Sphinx. The source of the manual resides in the doc/ directory.

You need Python 3.4 or newer to install Sphinx for Flycheck’s documentation. On macOS it is recommended that you use Homebrew to install the latest Python version with brew install python3. On Linux you should be able to obtain Python 3.4 from the package manager of your distribution.

With Python 3 installed change into the doc/ directory and run make init to install Sphinx and related tools required for Flycheck’s documentation. We recommend that you use virtualenv to avoid a global installation of Python modules. make init will warn you if you do not.

When editing documentation run make html-auto to view the results of your edits. This target runs a local webserver at http://localhost:8000 which serves the HTML documentation and watches the documentation sources for changes to rebuild automatically. When you have finished your edits it is a good idea to run make linkcheck to verify all links in the documentation. Note that this target can take a while especially when run on a clean build.

Run make help to see a list of all available Make targets for the documentation.

Documentation pull requests work in the same way as other pull requests. To find documentation issues sort by the documentation label.

Issue management

We use Github labels for basic issue management:

  • The red “bug” label denotes critical bugs in Flycheck that must be fixed urgently.

  • Violet labels describe the area of Flycheck the issue belongs to.

  • The green “beginner friendly” label denotes easy tasks for newcomers to the project.

  • Orange labels denote blockers.

  • Grey labels indicate resolutions to issues.

Out of tree contributions

There are many ways that you can contribute to Flycheck that go beyond this repository.

Answer questions in our Gitter channel or on StackExchange.

Participate in Flycheck discussions in other Emacs communities and help users with troubles.

Write extensions for Flycheck.

This contributing guide is heavily inspired by Rust’s excellent contributing information.