Skip to content

Latest commit

 

History

History
73 lines (50 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

73 lines (50 loc) · 4.23 KB
Raw

Contributing

HAX is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully, these rules make things go more smoothly.

As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a pull request.

Beginner focused information can be found below in Open a Pull Request and Code Review.

Communication

Reporting issues? Our unified issue queue is a good place for this: https://github.com/haxtheweb/issues/issues Need to discuss something via chat? Our Discord can be joined here.

GitHub workflow

We work primarily using pull requests and forks. In order to work most effectively, we ask that you FORK any project you are wanting to contribute to in our ecosystem. After taking a fork, submit a pull request while pointing to the associated issue tied to this pull request.

Opening a Pull Request

Pull requests are often called a "PR". HAX generally follows the standard github pull request process.

Common new contributor PR issues are:

  • Not referencing the issue that the PR resolves
  • Not describing the scope of the solution effectively
  • Include mentions (like @person) and keywords which could close the issue (like fixes #xxxx) in commit messages.

Code Review

To make it easier for your PR to receive reviews, consider the reviewers will need you to:

  • Write good commit messages
  • Break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue

When reviewing PRs from others The Gentle Art of Patch Review suggests an iterative series of focuses which is designed to lead new contributors to positive collaboration without inundating them initially with nuances:

  • Is the idea behind the contribution sound?
  • Is the contribution architected correctly?
  • Is the contribution polished?

Note: if your pull request isn't getting enough attention, you can use our Discord channel to get help finding reviewers.

Best practices

  • Write clear and meaningful git commit messages.
  • If the PR will completely fix a specific issue, include fixes #123 in the PR body (where 123 is the specific issue number the PR will fix. This will automatically close the issue when the PR is merged.
  • Make sure you don't include @mentions or fixes keywords in your git commit messages. These should be included in the PR body instead.
  • When you make a PR for small change (such as fixing a typo, style change, or grammar fix), please squash your commits so that we can maintain a cleaner git history.
  • Make sure you include a clear and detailed PR description explaining the reasons for the changes, and ensuring there is sufficient information for the reviewer to understand your PR.
  • Additional Readings:

Testing

Unit tests are ideal but not required to be written for proposed changes and enhancements.

Security

If you discover what you deem to be a critical security issue please reach out on our Discord channel privately to discuss whether this should be resolved in the open prior or if disclosure should happen after a solution has been crafted.