Skip to content

Latest commit

 

History

History
147 lines (102 loc) · 4.27 KB

CONTRIBUTING.md

File metadata and controls

147 lines (102 loc) · 4.27 KB
Raw

Guidelines For Reporting An Issue/Feature

So you've found a bug or have a great idea for a feature. Here's the steps you should take to help get it added/fixed in emacs-elixir

  • First, check to see if there's an existing issue/pull request for the bug/feature. All issues are at https://github.com/elixir-lang/emacs-elixir/issues and pull reqs are at https://github.com/elixir-lang/emacs-elixir/pulls.

  • If there isn't one there, please file an issue. The ideal report includes:

    • A description of the problem/suggestion.

    • How to recreate the bug.

    • Versions of your:

      • operating system
      • elixir-mode
      • emacs

    • Ideally, creating a pull request with a (failing) test case demonstrating what's wrong. This makes it easy for us to reproduce & fix the problem.

You might also hop into the IRC channel (#elixir-lang on irc.freenode.net) & raise your question there, as there may be someone who can help you with a work-around.

Guidelines For Contributing Code

If you're ready to take the plunge & contribute back some code, the process should look like:

  • Fork the project on GitHub into your own account.
  • Clone your copy of emacs-elixir.
  • Make a new branch in git & commit your changes there.
  • Push your new branch up to GitHub.
  • Again, ensure there isn't already an issue or pull request out there on it. If there is & you feel you have a better fix, please take note of the issue number & mention it in your pull request.
  • Create a new pull request (based on your branch), including what the problem/feature is, versions of your software & referencing any related issues/pull requests.

In order to be merged into emacs-elixir, contributions must have the following:

  • A solid patch that:

    • is clear.
    • works across all supported versions of Emacs (24+).
    • follows the existing style of the code base.
    • comments included as needed.

  • A test case that demonstrates the previous flaw that now passes with the included patch.

If your contribution lacks any of these things, they will have to be added by a core contributor before being merged into emacs-elixir proper, which may take substantial time for the all-volunteer team to get to.

How to run tests

There are three tools that helps us to test emacs-elixir:

  • EVM - a command-line tool which allows you to easily install, manage, and work with multiple Emacs versions.
  • Cask - a project management tool for Emacs that helps automate the package development cycle.
  • Ert-runner - a tool for Emacs projects tested using Ert.

Emacs Version Manager

To install EVM, run:

$ sudo mkdir /usr/local/evm
$ sudo chown $USER: /usr/local/evm
$ curl -fsSkL https://raw.github.com/rejeep/evm/master/go | bash
$ export PATH="~/.evm/bin:$PATH" # Add it to your .bashrc or analogue

To list all available Emacs versions you can install, run:

$ evm list

To install a version (for example emacs-24.3-bin), run:

$ evm install emacs-24.3-bin

Read more about EVM.

Cask and ert-runner

To install Cask, run:

$ curl -fsSkL https://raw.github.com/cask/cask/master/go | python
$ export PATH="~/.cask/bin:$PATH" # Add it to your .bashrc or analogue

To install Ert-runner, run:

$ cd path/to/emacs-elixir
$ cask install # install ert-runner
$ EMACS=`evm bin emacs-24.3-bin` cask install # install ert-runner for Emacs 24.3

Examples of usage

  • Run all tests:
$ cask exec ert-runner
  • Run all tests for Emacs 24.3:
$ EMACS=`evm bin emacs-24.3-bin` cask exec ert-runner

Run all tests which are tagged fontification:

$ cask exec ert-runner -t fontification

Run all tests with elixir-smie-verbose-p equal to t:

$ cask exec ert-runner --verbose

Run all tests interactively:

$ cask exec ert-runner --win

Run all tests which are tagged fontification for Emacs 24.3 interactively:

$ EMACS=`evm bin emacs-24.3-bin` cask exec ert-runner -t fontification --win

Read more about Cask and Ert-runner.