From c73709c36aa96ec1806987f6c3b51a306495c05f Mon Sep 17 00:00:00 2001 From: Andrew Rynhard Date: Mon, 7 Dec 2020 12:36:04 -0800 Subject: [PATCH] chore: update CONTRIBUTING.md This document can be simplied as the `Makefile` and pull request status deliver a lot of the supplied information. This removes a lot of redundant information and only touches on the more important ideas. Signed-off-by: Andrew Rynhard --- CONTRIBUTING.md | 110 ++++-------------------------------------------- 1 file changed, 9 insertions(+), 101 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1cdc48959..349ac68bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,108 +1,16 @@ # Contributing -First of all, thank you! -We value your time and interest in making Talos a successful open source project. +## Developer Certificate of Origin -## What We Need +All commits require a [DCO](https://developercertificate.org/) sign-off. +This is done by committing with the `--signoff` flag. -There are a number of ways you can help! -We are in need of both technical and non-technical contributions. -Even just mentioning the project to a friend, colleague, or anyone else for that matter, would be a huge help. -We need writers, bloggers, engineers, graphics designers — you name it, we need it. +## Development -## Guidelines +The build process for this project is designed to run entirely in containers. +To get started, run `make help` and follow the instructions. -Let's talk about some of the guidelines we have when making a contribution to Talos. +## Conformance -### Git Commits - -You probably noticed we use a funny way of writing commit messages. -Indeed we do, but its based on a specification called [Conventional Commits](https://www.conventionalcommits.org). -Don't worry, it won't be _too_ much of hassle. -We have a small tool that you can use to remind you of our policy. - -```bash -go get github.com/autonomy/conform -cat <`. -It is not necessary to cryptographically sign commits with GPG. - -### Pull Requests - -To avoid multiples CI runs, please ensure that you are running a full build before submitting your PR, and branches should be squashed to a single commit. -To run some local tests you can use the included Makefile in this repo. -For example to run the conformance tests: - -```bash -$ make conformance -docker run --rm -it -v /Users/user/projects/talos:/src -w /src docker.io/autonomy/conform:v0.1.0-alpha.19 -POLICY CHECK STATUS MESSAGE -commit Header Length PASS -commit Imperative Mood PASS -commit Header Case PASS -commit Header Last Character PASS -commit DCO PASS -commit Conventional Commit PASS -commit Spellcheck PASS -commit Number of Commits PASS -commit Commit Body PASS -license File Header PASS -``` - -Make sure all tests pass before creating a PR. - -## Developing - -To start developing for Talos you will need at least `GNU Make` and `Golang` v1.11. - -From there you can bootstrap the rest of the toolchain and install Golang dependencies with the following commands: - -```bash -GO111MODULE=on go get -make ci -``` - -## Make Targets - -In the `Makefile` there are a variety of targets, the most common are: - -- `kernel` creates the `vmlinuz` Linux kernel executable. -- `initamfs` creates the `initramfs.xz` initial RAMdisk filesystem. -- `image-vanilla` creates the `image.raw` file that can be used as a image volume for VMs. -- `talosctl-linux-amd64` and `talosctl-darwin-amd64` make the `talosctl` CLI tool for Linux & OSX respectively. -- `rootfs` creates an archive of the root filesystem preloaded with all the components needed to launch Talos & Kubernetes. - -## Buildkit - -Talos uses Moby [buildkit](https://github.com/moby/buildkit) for concurrent and cache-efficient builds. -By default, a buildkit service is started locally, but if you want to offload the builds to another server, you can start a buildkit service with the following command: - -```bash -docker run --detach --privileged --restart always --publish 1234:1234 moby/buildkit --addr tcp://0.0.0.0:1234 -``` - -Then using the `BUILDKIT_HOST` environment variable before running any `make` target, E.G. - -```bash -BUILDKIT_HOST=tcp://192.168.1.50:1234 make initramfs -``` - -### Docker for mac - -To enable building buildX on Docker for Mac you need to enable the experimental features in the docker app. -To enable this go to: Docker -> preferences -> Command Line -> "Enable experimental features" should be toggled on. - -## VScode extensions - -Visual studio code is a editor which is widely used, and has some neat features to make your life easier. -Below is a list of extensions that can help while developing for Talos. - -- [Markdown lint](https://marketplace.visualstudio.com/items/DavidAnson.vscode-markdownlint) -- [Golang support](https://marketplace.visualstudio.com/items?itemName=golang.Go) +To very conformance status, run `make conformance`. +This runs a series of tests on the working tree and is required to pass before a contribution is accepted.