Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
113 lines (82 loc) · 6.67 KB

CONTRIBUTING.md

File metadata and controls

113 lines (82 loc) · 6.67 KB

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.

Setting up a Development Environment

HAX provides several options to make onboarding accessible for new contributors.

  1. Use our Dev Container for a ready-made environment powered by Docker
  2. Use the built-in hax party module to develop from your local device, leveraging your existing haxtheweb/create install

Either way, we'll get you up and running with tooling, repositories, and the community.

Dev Container

  • Install Docker (or another container runtime)
    • Windows
      • Ensure that you select the WSL 2 Backend option
      • Restart after install
      • Certain Windows editions are bundled with an old WSL 2 version. If Docker Desktop warns that WSL 2 is outdated, please update through the Windows Store or run wsl --update in PowerShell.
    • macOS
    • Linux
    • Dev Containers are broadly supported across OCI-compliant runtimes like Docker, Podman, and OrbStack.

After this step you're ready to go!

  1. Clone the project with Git or GitHub Desktop
  2. Select Open in VS Code
  3. Select Install Recommended Extensions
  4. Select Reopen in Container!

Local

System dependencies

hax party works great with just git, but contributors can get some extra convenience with GitHub's own gh utility. (You can fork repos directly from the CLI, rather than visiting the browser every time!)

Node.js configuration

For a local development environment, the official release of HAX may already be installed through npm install -g @haxtheweb/create. You'll need to give this project precedence over the global Node.js install.

  • Run npm link in the root of the repository

This overrides the global install, so that every hax command references your changes to the project. The typical workflow includes two terminal windows:

  1. Run npm run dev in the first terminal to watch for changes, then rebuild
  2. Use the second terminal interactively with hax, inspecting and testing your work

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.