👍🎉 First off, thanks for taking the time to contribute! 🎉👍
The following is a set of guidelines for contributing to erlang_ls,
which is hosted in the erlang-ls
Organization on GitHub. These are
mostly guidelines, not rules. Use your best judgment, and feel free to
propose changes to this document in a pull request.
All contributions are highly welcome in the form of code, documentation, bug reports and opened issues.
Whenever reviewing or commenting other people contributions, please keep a positive attitude. Treat other contributors respectfully and be constructive, always appreciating the effort and the time other contributors are putting into the project.
erlang_ls is an implementation of Microsoft's Language Server
Protocol, so you should be familiar with it. You can read about the
protocol here. You can find the detailed specification
here.
If you are curious about the erlang_ls project itself, you can also
have a look to the wiki.
If you have a question, please do not open an issue. Instead, start a
discussion using the channel named #language-server in the Erlanger
Slack. Feel free to open an issue if you:
- have a specific feature request,
- would like to report a bug.
Prefer small, reviewable changes over big changes.
Always discuss major contributions or refactoring with the authors, before starting. This will avoid duplicated efforts and ensure everyone is aligned and agrees with the planned changes.
Before starting to work on a big task, assign the task to yourself. If a task is assigned to someone else and you would like to help out, please contact the assigned person first.
Before starting a major task, always describe the problem you are trying to solve in an issue. Explain the way you plan to address a problem. This may save you a lot of time during the review phase.
We try to follow the following conventions in the Erlang code:
Even if you are not using punch cards for writing code and our screens can usually display more than those characters, we still find that this rule encourages writing of simple, straightforward code.
We prefer this:
#{ one = One
, two = Two
}
Over:
#{ one = One,
two = Two
}
We prefer this:
First = {first , 1},
Second = {second , 2},
TwentyFour = {twentyfour , 24}
Over:
First = {first, 1},
Second = {second, 2},
TwentyFour = {twentyfour, 24}
Whenever possible, we will try to enforce these conventions via linters. We also maintain a list of rebar3 templates that you can use when creating new Erlang LS modules. Please refer to the official rebar3 documentation for more information on how to use a rebar3 template.
- Use descriptive commit messages.
- Prefix every commit message with the issue number in the form
[#NNN]. - Use imperative form (prefer
Move function...overMoves function). - Avoid past tense.
- Use a final dot.
A good commit may look like this:
[#42] Discover the meaning of life.
- Always be constructive when providing feedback (e.g. be explicit on what could be improved and how)
- Use GitHub suggestion blocks for fixing typos and small mistakes
- Positive feedback is as important as negative feedback
- Only the Pull Request author(s) should push changes to the branch under review
- Reviewers should be as responsive as possible in providing their reviews.
- Every review should be completed via either an Approve or a Request Changes action. Not selecting either option should be considered as a review in progress. While it is possible to simply add a comment without expressing a general opinion on the Pull Request, this option should be used with care, since it does not give a clear indication about the review. This applies to project maintainers and reviewers whose opinion has been explicitly requested in the PR. It is ok (and encouraged) for extra reviewers or other contributors to leave comments on a PR.
- Code reviews should be completed within a reasonable time window. Leaving comments in time-separated bulks is discouraged.
- It is not acceptable to mark a Pull Request via a needs work without further explanation.
- PR Conversations can be marked as resolved by the PR author, but
only if at least one of the following conditions holds:
- the issue is addressed via a code change;
- the issue will be tackled in a follow up Pull Request (a follow-up ticket should be created and linked in this case);
- the issue is marked as a won't fix and an explanation is provided.
- Once a PR conversion is marked as resolved, it is the responsibility of both the Pull Request author and the reviewer to verify that the original issue has been properly addressed (either via a code change or a clear explanation or follow-up ticket).
- When a trivial task (e.g. fixing a typo) is marked as done via a code change, no further explanation is required. A Fixed comment can be added by the author of the Pull Request, but it is not mandatory.
- Nit-picking comments must be prefixed by the
Nit:prefix. If possible, they should be addressed via a code suggestion block. The Pull Request author is encouraged to fix nit-picking comments, but they should not be considered as blockers. - It is not acceptable to mark a Pull Request as a Request Changes in case only nit-picking comments are present.
- In case of post-merge comments, the original author of the Pull
Request must be pinged directly via a
@mention. - It is acceptable to open a Pull Request to get some early feedback from other team members, even if the changes included in the Pull Request are not in a reviewable state, yet. In this case, though, a Draft Pull Request should be used.
Dealing with strings in Erlang can be tricky. Within the Erlang LS
project we try as much as possible to ensure proper Unicode handling
of strings. When converting lists of characters into binaries and
back, please use the utilities provided in the els_utils module:
els_utils:to_list(Binary)
els_utils:to_binary(List)You can also read here for more information on the topic.
These CONTRIBUTING notes are partially inspired by the awesome ones of the Atom and Rails projects.