Skip to content

Latest commit

 

History

History
209 lines (150 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

209 lines (150 loc) · 10.3 KB
Raw

Contributing guidelines

This document describes how to contribute to the project.

Prerequisites

  • go version v1.18+.
  • docker version 17.03+.
  • kubectl version v1.11.3+.
  • kustomize v4+
  • Access to a Kubernetes v1.21+ cluster (the easiest way to develop is using Kind).

Contributing steps

  1. Submit an issue describing your proposed change to the repo in question.
  2. The repo owners will respond to your issue promptly.
  3. Fork the desired repo, develop and test your code changes.
  4. Submit a pull request.

How to build RaptorML locally

Note that, by building RaptorML from the source code we are allowed to test the changes made locally.

  1. Run the following command to clone your fork of the project locally

    $ git clone git@github.com:<user>/raptor.git

  2. Build the project locally

    make build

    It's also possible to build the docker images locally using the following command:

    make docker-build

Set up a local development cluster

To develop RaptorML locally, you can use Tilt, with the pre-configured setup to build a local setup.

  1. Install Tilt

  2. Create a local development cluster. We're highly recommending using Kind and ctlptl to create a local cluster.

    Kind is a tool for running local Kubernetes clusters using Docker container “nodes”. ctlptl is a tool for managing local Kubernetes clusters. ctlptl is a tool for managing local Kubernetes clusters. It can create a local cluster using kind and configure it to be ready for development.

    ctlptl create cluster kind --registry=ctlptl-registry --name kind-raptor

    This command will create a local Kind cluster, with a local registry ready to be used.

  3. Start the Tilt environment

    tilt up

    This command will start the Tilt environment, which will build the docker images and deploy the RaptorML components to the local cluster.

The Tilt environment will watch for changes in the source code and will automatically rebuild the images and redeploy the components.

In addition, it'll create the necessary resources to run RaptorML locally, including Redis, Ingress controller(ngnix), and Prometheus - and will automatically create port-forwarding to the local cluster.

While developing Raptor, the Tilt environment will watch for changes in the source code and will automatically rebuild the images and redeploy the components.

We're also attaching to this environment a go debugger, which will allow us to debug the code while running it locally.

You can connect to the debugger on port 2345 for the raptor-controller-core, and 2346 for the raptor-historian.

What to do before submitting a pull request

  1. Run the script make generate to update/generate autogenerated files.
  2. Run make test
  3. Run make test-e2e
  • e2e tests use kind and kustomize. Make sure that you have the latest versions of these tools installed on your machine.

IMPORTANT: The make generate is very helpful. By using it, you can check if good part of the commands still working successfully after the changes. Also, note that its usage is a pre-requirement to submit a PR.

Following the targets that can be used to test your changes locally.

Command Description Is called in the CI?
make test Runs tests yes
make test-e2e Runs Integration tests yes
make lint Run golangci lint checks yes
make lint-fix Run golangci to automatically perform fixes no
make generate Generate autogenerated files yes
make build Build the binaries yes
make docker-build Build docker images yes
make kind-load Load docker images to local Kind cluster no
make buf-build Build the proto files yes

PR Process

Individual commits should not be tagged separately, but will generally be assumed to match the PR. For instance, if you have a bugfix in with a breaking change, it's generally encouraged to submit the bugfix separately, but if you must put them in one PR, mark the commit separately.

Commit Message Format

We are using Conventional Commits to standardize our commit messages. This allows us to automatically generate changelogs and release notes, to create a more readable git history and to automatically trigger semantic versioning. This way no human is directly involved in the release process and the releases are guaranteed to be unromantic and unsentimental.

Please make sure to follow the following format when writing commit messages and PR titles:

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ [optional] Commit Scope, i.e.: LabSDK, pyexp, cli, engine, ...
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test

[optional body]

[optional footer(s)]

We support the following Conventional Commit Types:

Type Title Description
feat Feature A new feature. (this correlates with MINOR in Semantic Versioning)
fix Bug fixes A bug fix.
docs Documentation Documentation only changes
style Styles Changes that do not affect the meaning of the code (white-space, formatting, missing colons, etc)
refactor Code Refactoring A code change that neither fixes a bug nor adds a feature
perf Performance Improvements A code change that improves performance
test Tests Adding missing tests or correcting existing tests
build Builds Changes that affect the build system or external dependencies (example scopes: makefile, upgrade modules, bash scripts)
ci Continuous Integration Changes to our CI configuration files and scripts (example scopes: github actions)
chore Chores Other changes that don't modify src or test files
revert Reverts Reverts a previous commit. Commit body should contain the reason and the SHA of the reverted commit

Examples:

fix: Correct typo.
feat: Add support for COUNT aggregation .
refactor!: Change the get feature API.
feat(labsdk): Add new way to export features

Breaking changes

Breaking changes, are changes that break the public API of the project. They are marked with a ! after the type/scope, e.g.: refactor!: change the python API. This will trigger a MAJOR version bump when the commit is merged.

Breaking changes should be avoided if possible, but if they are necessary, they should be properly communicated to the users and developers of the project.

💡 Note that since PR titles only have a single line, you have to use the ! syntax for breaking changes.

Contributing major changes

Contributing major changes such as new features or refactoring are always welcome! That being said, they require an extra care for us to be able to review them before merging them. To do this, we need you to:

  1. Explain in details the proposed change, including the motivation, the proposed solution, and the architecture(when applicable).
  2. Provide at least one example of how to use the proposed change (when applicable; i.e new feature).
  3. Write a test for the proposed change (e2e / unit test).

Where the CI Tests are configured

See the action files to check its tests, and the scripts used on it.

Profiling

If you find yourself in a need to profile the app, it's possible by adding the following lines to the main.go:

mgr.AddMetricsExtraHandler("/debug/pprof/", http.HandlerFunc(pprof.Index))
mgr.AddMetricsExtraHandler("/debug/pprof/cmdline", http.HandlerFunc(pprof.Cmdline))
mgr.AddMetricsExtraHandler("/debug/pprof/profile", http.HandlerFunc(pprof.Profile))
mgr.AddMetricsExtraHandler("/debug/pprof/symbol", http.HandlerFunc(pprof.Symbol))
mgr.AddMetricsExtraHandler("/debug/pprof/trace", http.HandlerFunc(pprof.Trace))

Code of conduct

Participation in the RaptorML community is governed by the Kubernetes Code of Conduct.