Skip to content

Latest commit

 

History

History
134 lines (94 loc) · 6.55 KB

CONTRIBUTING.md

File metadata and controls

134 lines (94 loc) · 6.55 KB
Raw

Welcome to heimdall's contributing guide

Thank you for investing your time in contributing to this project! Any contribution you will make, will make heimdall better for everyone ✨!

Before you continue, here are some important resources:

How can I contribute?

There are many ways you can contribute to heimdall. Here are some ideas:

  • Give this project a star: It may not seem like much, but it really makes a difference. This is something that everyone can do to help. Github stars help the project gaining visibility and stand out.
  • Join the community: Helping people can be as easy as by just sharing your own experience. You can also help by listening to issues and ideas of other people and offering a different perspective, or providing some related information that might help. Take a look at heimdall's Discussions. Bonus: You get GitHub achievements for answered discussions 😉.
  • Review documentation: Most documentation just needs a review for proper spelling and grammar. If you think a document can be improved in any way, feel free to do so by opening a PR.
  • Help with open issues: There are many open issues. Some of them may lack necessary information, some may be duplicates of older issues. Most are waiting for being implemented.
  • You spot a problem: Search if an issue already exists. If a related issue doesn't exist, please open a new issue using a relevant issue form.

Disclosing vulnerabilities

Please disclose vulnerabilities by making use of Security Advisories. Do not use GitHub issues for that.

Contribute content

Unless you are fixing a known bug, we strongly recommend discussing it with the core team via a GitHub issue or in heimdall's Discussions or Discord (preferred) before getting started.

Important: Only PRs with signed commits will be accepted.

The general process is as follows:

Set up your local development environment to contribute to heimdall:

  1. Fork, then clone the repository.

    > git clone https://github.com/your_github_username/heimdall.git
> cd heimdall
> git remote add upstream https://github.com/dadrus/heimdall.git
> git fetch upstream

  2. Install required tools:

  • Just, which is used to lint, build and test the project via CLI.
  • Docker if you want to build and work with docker images.
  • Golang.
  • golangci-lint to lint the code.
  • hadolint to lint the Dockerfiles.
  • Helm to lint and work with Helm Chart provided with heimdall.
  • go-licenses to ensure all dependencies have allowed licenses.
  • kubeconform to validate the manifests generated by Helm.

  1. Verify that tests and other checks pass locally.

    > git pull
> git checkout main
> just lint
> just test

  2. When creating the PR, please follow the guide, you'll see in the PR template to make the review process more smoothly.

  3. At this point, you're waiting on us to review your changes. We try to respond to issues and pull requests within a few days, and we may suggest some improvements or alternatives. Once your changes are approved, one of the project maintainers will merge them.

Contribute Code

After having installed the tools listed above:

  1. Create a new feature branch.

    > git checkout -b cool_new_feature

  2. Make your changes, and verify that all tests and lints still pass.

    > just lint
> just test

  3. When you're satisfied with the change, push it to your fork and make a pull request.

    > git push origin cool_new_feature
# Open a PR at https://github.com/dadrus/heimdall/compare

Contribute Documentation

The entire documentation is located under docs with the actual content located under docs/content. In that folder you can see the top level sections

  • "docs" - containing the documentation of the project, and
  • "guides" - containing the different guides.

The contents are written in Asciidoc, a lightweight markup langauge, designed to write technical documentation.

To contribute to the documentation, the only tools you need is actually Docker and Just. After having these two in place:

  1. Create a new feature branch

    > git checkout -b cool_new_documentation_update

  2. Start the docs server with

    > just run-docs

    and open the browser by following the link shown in the output of the started server. This allows you working on your changes and observing the results immediately.

  3. Make your changes, and verify that what you've written looks nice and is rendered properly.

  4. When you're satisfied with the change, push it to your fork and make a pull request.

    > git push origin cool_new_documentation_update
# Open a PR at https://github.com/dadrus/heimdall/compare

Contribute Examples

There are many examples for docker and kubernetes to support people interested in heimdall in getting started with it. All of these are located under the examples directory.

As with other contribution options addressed above

  1. Create a new feature branch

    > git checkout -b cool_new_example

  2. Work on your example. While working on it, please ensure, you do not break existing ones.

  3. When you're satisfied with your result, push it to your fork and make a pull request.

    > git push origin cool_new_example
# Open a PR at https://github.com/dadrus/heimdall/compare