Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
209 lines (143 loc) · 7.72 KB

CONTRIBUTING.md

File metadata and controls

209 lines (143 loc) · 7.72 KB
Raw

Contributing

Thank you for getting involved! Before you start, please familiarize yourself with the documentation.

Please follow our Code of Conduct when interacting with this project.

Opening an issue, starting a discussion, asking a question

This project uses the GitHub issue tracker. Check the existing issues before submitting to avoid duplicates.

If you have a broader topic to discuss or a question, please open a discussion instead.

Pull requests

Contrast is licensed under the BUSL. When contributing, you also need to agree to our Contributor License Agreement.

PRs that aren't labeled no changelog need a PR description that's meaningful to the end user, as they will be included in the release notes. All other impacts imply that the PR has a visible impact on the end user.

Git conventions

Commit history on PRs should be clean and meaningful. Before submitting a PR, make sure to cleanup you history, for example using interactive rebase.

Most commits will use a prefix to indicate the area of change: <prefix>: <title>. Common titles are the top-level directory your change was made in (for example docs), a subdirectory (e2e/reproducibility), or the nix attribute (path) that was changed (kata.runtime). Further, there are some meta-prefixes like ci and treewide used. Use a meaningful commit title that's precise, short and descriptive for your change. You can find many guides and examples online. Commit message bodies aren't required, but recommended on PRs with many non-trivial commits.

Wherever possible, each commit should be functional (it should build, have tests and CI passing). It's okay to deviate from this rule in situations where a non-functional commit improves review-ability a lot. In general, commit history is to document the change and ease the review process. Make sure file moves are detected by git, do them in a separate commit where needed. If you are renaming things and it causes changes in many lines, do it in a separate commit.

When addressing review feedback, be sure to it cleanly with regard to your existing commits. For smaller PRs, you can directly amend the commit and force-push the update (remember to always use --force-with-lease). GitHub will have a button to show the diff of your last force-push. Push a rebase separate from addressed changes. If you need to push more often, this method might fail. In this case, and on larger PRs (with many commits, reviewers or changes to address), you should use fixup commits instead. Make sure to target the right commit with the fixup commit. After the PR has been approved, you can then rebase and --autosquash your fixup commits. In some situations, tools like git-absorb might come in handy (but beware of fixup commit flooding). If you are struggling with your git history during the review process, please ask a more experienced contributor for help.

Development setup

Note

If you are developing on macOS/Darwin, you have to first follow the experimental developer documentation for macOS, and then proceed with the rest of the setup.

  1. Install Nix

    Enable the experimental features nix-command and flakes in your Nix configuration.

    On NixOS (in your config):

    nix.settings.experimental-features = [
    "nix-command"
    "flakes"
];

    On other systems (in /etc/nix/nix.conf):

    experimental-features = nix-command flakes

  2. Configure Nix to allow use of extra substituters, and profit from our cachix remote cache. To allow using additional substituters from the flake.nix, add your user name (or the wheel group) as trusted-user in your nix config.

    On NixOS (in your config):

    nix.settings.trusted-users = [ "root" "@wheel" ];

    On other systems (in /etc/nix/nix.conf):

    trusted-users = root @wheel

    See Nix manual section on substituters and trusted-users for details and consequences.

    When first using a Nix command on the Contrast flake, accept the additional substituters permanently when prompted.

  3. Enter the development environment with

    nix develop .#

    Or activate direnv to automatically enter the nix shell. It's recommended to use nix-direnv. If your system ships outdated bash (MacOS), install direnv via package manager.

    direnv allow

    Additionally, you may want to add the VSCode extension.

    You may also want to configure your editor. Check .vscode/settings.json or .nvim.lua for details.

  4. Log into GCP.

    nix shell nixpkgs#google-cloud-sdk -c gcloud auth login

  5. Configure access to your personal GitHub container registry

    Visit https://github.com/settings/tokens/new and create a new Personal access token (classic) with write:packages permission.

    Then run

    crane auth login ghcr.io -u <GITHUB USERNAME> -p <YOUR PERSONAL ACCESS TOKEN>

    This will add your credential in ~/.docker/config.json.

  6. Execute and follow instructions of

    just onboard

  7. Configure your cluster's credentials

    just get-credentials

Warning

get-credentials <system> will fetch a secret containing the pre-configured kubeconfig for the specified system from Edgeless's Google Cloud project. If you aren't part of Edgeless Systems you will need to setup your own cluster by following https://docs.edgeless.systems/contrast/howto/cluster-setup/bare-metal

Tip

Use get-credentials-dev to obtain the kubeconfig for the development server (requires access).

Deploy

The usual developer flow is available as a single target to execute:

just [default <deployment-name>]

This will build, containerize and push all relevant components. Ensure the pushed container images are accessible to your cluster. The manifest will the be generated (contrast generate).

Further the flow will deploy the selected deployment and wait for components to come up. The manifest will automatically be set (contrast set) and the Coordinator will be verified (contrast verify). The flow will also wait for the workload to get ready.

This target is idempotent and will delete an existing deployment before re-deploying.

All steps can be executed as separate targets. To list all available targets and their description, run

just --list

Tip

After the first time you upload contrast's images in your personal GitHub repository, you will need to explicitly change their visibility to public so that they can be downloaded from the test infrastructure. This step can't be automated and needs to be done manually for each image by visiting https://github.com/<YOUR USER>/?tab=packages, clicking on each image, then "Package settings" on the right.

Cleanup

  • Undeploy your deployment with

    just undeploy

  • Undeploy your deployment and clean the workspace with

    just clean

Maintenance tasks

  • Run code generation

    just codegen

  • Format all code

    just fmt