Skip to content

Latest commit

 

History

History
126 lines (98 loc) · 5.16 KB

ELIXIR.md

File metadata and controls

126 lines (98 loc) · 5.16 KB
Raw

General Elixir Guidelines

Table of Contents

  1. Coding Guidelines
  2. Build Tools
  3. Test Coverage
  4. Documentation
  5. Project Setup
  6. Dependencies
  7. Data for hex.pm
  8. Travis.yml
  9. Building and Releasing
  10. Steps for New Releases / Version Bumps

Coding Guidelines

Make sure you comply with this elixir style guide. In order to automate the style checking, install Credo and run it before creating a new Pull Request. If possible, always run credo with the strict flag: mix credo --strict. Another must-have is to enable Credo CI to automatically check your updates in GitHub.

Build Tools

Before pushing a new Pull Request, run your unit tests locally and never push them if something is not green. If the project is open-source, setup Travis CI to automatically run your unit tests after each new change. Remember to add a badge to your README file informing visitors that the build is passing.

Test Coverage

Always aim at 100% code coverage for your tests. Don't deliver your code unless it has at least 75% coverage. For a deeper explanation, check this blog post. Install excoveralls in your project and check the coverage before pushing new changes. If it's open-source, make sure to setup up coveralls.io and add the coverage badge to your README file. When using Travis CI, you can ask it to trigger a code coverage task after a successful build (see .travis.yml example below).

Documentation

Document exported functions in all your modules and the modules themselves, especially in open-source projects, which should be documented using @moduledoc and @doc comments. Remember to install ex_doc and have a proper task to build the doc files when needed. For open-source projects, Inch CI can be of use to check the documentation coverage, and you can also integrate it with Travis CI (check .travis.yml example below).

Project Setup

Dependencies

All deps used in the default profile should use the packages in hex.pm. For deps used in other profiles, etc. it's a nice to have, but not mandatory. When possible, assign the project to Hex Faktor to be informed of out-of-date dependencies.

Data for hex.pm

The project's mix.exs file should include hex.pm package and description attributes. For instance:

  @version "2.1.0"

  def project do
    [
      app: :your_app,
      version: @version,
      ...
      # Hex
      description: description,
      package: package
    ]
  end

  defp description do
    """
    A short project description
    """
  end

  defp package do
    [
      maintainers: ["Inaka"],
      licenses: ["Apache 2.0"],
      links: %{"GitHub" => "https://github.com/inaka/your_app"},
      files: ~w(mix.exs README.md CHANGELOG.md lib),
      links: %{
        "GitHub"  => "https://github.com/inaka/your_app",
        "Docs"    => "http://hexdocs.pm/your_app/",
        "Blog"    => "http://inaka.net/blog/…", # If there is one
        "Example" => "https://github.com/inaka/your_app/tree/master/example"
      }
    ]
  end

Travis.yml

Especially for open-source projects integrating open code checkers with Travis CI builds, the .travis.yml file in your project root folder should look similar to:

  language: elixir
  elixir:
    - 1.2.3
  otp_release:
    - 18.2.1
  env:
    - MIX_ENV=test
  script: mix coveralls.travis
  after_script:
    - mix deps.get --only docs
    - MIX_ENV=docs mix inch.report

Building and Releasing

We use hex.pm for open-source projects.

To generate the release you must update the version in your mix.exs and run:

  $ mix hex.publish

Steps for New Releases / Version Bumps

  1. Increase the version number inside the project's mix.exs file.
  2. In the project's root directory, execute the script: github_changelog_generator -t [YOUR_ACCESS_TOKEN] --future-release [NAME OF FUTURE RELEASE].
  • Install github_changelog_generator as a ruby gem: $ gem install github_changelog_generator
  • If you don't have a GitHub access token already, create a new one.
  1. Commit those changes and create a pull request to get them merged into master.
  2. Create the new release in Github (this automatically creates the tag).
  • To do this, go to the project's home page, Releases and press the Draft a new release button.
  • Use [NAME OF FUTURE RELEASE] as its name.
  • Add To see what's new check the [CHANGELOG](CHANGELOG.md) as the change's description.
  1. Optionally, publish the project to hex.pm using mix hex.publish
  2. Update hex.pm docs for the project using mix hex.docs
  3. 💥