CONTRIBUTING.md

Contributing to kerl

1. License
2. Reporting a bug
3. Requesting or implementing a feature
4. Submitting your changes
   1. Code Style
   2. Committing your changes
   3. Pull requests and branching
   4. Credits

License

kerl is licensed under The MIT License, for all code.

Reporting a bug

kerl is not perfect software and will be buggy.

Bugs can be reported via GitHub issues: bug report.

Some contributors and maintainers may be unpaid developers working on kerl, in their own time, with limited resources. We ask for respect and understanding, and will provide the same back.

If your contribution is an actual bug fix, we ask you to include tests that, not only show the issue is solved, but help prevent future regressions related to it.

Requesting or implementing a feature

Before requesting or implementing a new feature, do the following:

• search, in existing issues (open or closed), whether the feature might already be in the works, or has already been rejected,
• make sure you're using the latest software release (or even the latest code, if you're going for bleeding edge).

If this is done, open up a GitHub issues: feature request.

We may discuss details with you regarding the implementation, and its inclusion within the project.

We try to have as many of kerl's features tested as possible. Everything that a user can do, and is repeatable in any way, should be tested, to guarantee backwards compatible.

Adding support for your Linux distribution to scan for build pre-requisites

Erlang needs several packages to build correctly - many of which may or may not be present on a fresh OS install or docker image, so as a convenience, kerl tests for these packages before it attempts to build.

We currently have tests for many popular Linux distributions but the sheer number of them means we may not have support for yours. If you want to add it, here is what we are looking for:

• starting around line 700 are a series of _KPP_<distro>_ parameters.
• Inspect the /etc/os-release file and find out what your distribution is called there
• Use that name to name your variables.
• Add a new function in the style of _rpm() _dpkg() etc to probe your distribution's package manager
• Add the list of packages corresponding to names used by the package manager in another variable
• Add the package probe function name to a new variable so kerl knows how to drive its testing
• Test locally and submit the output from that test as a comment in your PR

Submitting your changes

Code Style

• do not introduce trailing whitespace
• indentation is 4 spaces, not tabs
• try not to introduce lines longer than 100 characters
• write small functions whenever possible, and use descriptive names for functions and variables
• comment tricky or non-obvious decisions made to explain their rationale
• the tool is linted with shellcheck and formatted with shfmt: make sure you run these locally to avoid CI issues (their options are listed in lint.yml)

Pre- continuous integration

Check out what out lint.yml GitHub action will do over your changes, when submitting them, namely regarding shell scripts, .md files, and .yml files (all linted).

Committing your changes

Merging to the master branch may be preceded by a squash.

While it's Ok (and expected) your commit messages relate to why a given change was made, be aware that the final commit (the merge one) will be the issue title, so it's important it is as specific as possible. This will also help eventual automated changelog generation.

Pull requests and branching

All fixes to kerl end up requiring a +1 from one or more of the project's maintainers.

During the review process, you may be asked to correct or edit a few things before a final rebase to merge things. Do send edits as individual commits to allow for gradual and partial reviews to be done by reviewers.

Credits

kerl has been improved by many contributors!