Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
161 lines (116 loc) · 5.2 KB

CONTRIBUTING.md

File metadata and controls

161 lines (116 loc) · 5.2 KB

Contributing to oidcc

Welcome!

We look forward to your contributions! Here are some examples how you can contribute:

We have a Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Any contributions you make will be under the Apache 2.0 License

When you submit code changes, your submissions are understood to be under the same Apache 2.0 that covers the project. By contributing to this project, you agree that your contributions will be licensed under its Apache 2.0 License.

Write bug reports with detail, background, and sample code

In your bug report, please provide the following:

  • A quick summary and/or background
  • Steps to reproduce
    • Be specific!
    • Give sample code if you can.
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening, or stuff you
  • tried that didn't work)

Please do not report a bug for a version of oidcc that is no longer supported (< 1.0.0). Please do not report a bug if you are using a version of Erlang or Elixir that is not supported by the version of oidcc you are using.

Please post code and output as text (using proper markup). Do not post screenshots of code or output.

Workflow for Pull Requests

  1. Fork the repository.
  2. Create your branch from main if you plan to implement new functionality or change existing code significantly; create your branch from the oldest branch that is affected by the bug if you plan to fix a bug.
  3. Implement your change and add tests for it.
  4. Ensure the test suite passes.
  5. Ensure the code complies with our coding guidelines (see below).
  6. Send that pull request!

Please make sure you have set up your user name and email address for use with Git. Strings such as silly nick name <root@localhost> look really stupid in the commit history of a project.

We encourage you to sign your Git commits with your GPG key.

Pull requests for new features must be based on the main branch.

We are trying to keep backwards compatibility breaks in oidcc to a minimum. Please take this into account when proposing changes.

Due to time constraints, we are not always able to respond as quickly as we would like. Please do not take delays personal and feel free to remind us if you feel that we forgot to respond.

Dual Language Support

This project contains both Erlang Code and Elixir Bindings and uses both rebar3 (Erlang) and mix (Elixir) package / build managers.

This is to ensure, that the library can be used from Erlang without needing Elixir and from Elixir with a nice interface.

Because of this, some tasks (like tests; see below) need to be called for both managers. Special consideration is required to change dependencies since they need to be patched for both managers and need to be kept in sync.

Coding Guidelines

This project comes with configured linters (located in rebar.config and .credo.exs in the repository) that you can use to perform various checks:

$ rebar3 lint # Elvis Linter (Erlang Code)
$ rebar3 hank # Dead Code Checker (Erlang Code)
$ mix credo # Credo Linter (Elixir Bindings)

This project comes with configuration (located in rebar.config and .formatter.exs in the repository) that you can use to (re)format your source code for compliance with this project's coding guidelines:

$ rebar3 fmt # Erlang Code
$ mix format # Elixir Bindings

This project uses dialyzer to perform static code checking. Run it to make sure that your code is valid:

$ rebar3 dialyzer # Erlang Code
$ mix dialyzer # Elixir Bindings

Please understand that we will not accept a pull request when its changes violate this project's coding guidelines.

Using oidcc from a Git checkout

The following commands can be used to perform the initial checkout of oidcc:

$ git clone git@github.com:erlef/oidcc.git

$ cd oidcc

Install oidcc's dependencies using rebar3 and mix:

$ rebar3 get-deps # Erlang Code
$ mix deps.get # Elixir Bindings

Running oidcc's test suite

After following the steps shown above, oidcc's test suite is run like this:

$ rebar3 eunit # Erlang Code Unit Tests
$ rebar3 ct # Erlang Code Integration Tests
$ mix test # Elixir Bindings Tests

Generating oidcc Documentation

To generate the documentation for the library, run:

$ mix docs