From 5c1565f7f17b3795b837cc0da514e9e93f720aff Mon Sep 17 00:00:00 2001 From: Kevin Flansburg Date: Wed, 26 May 2021 14:34:19 -0400 Subject: [PATCH] Add community docs (#12) * Add community docs * Typo --- README.md | 2 + docs/README.md | 8 + docs/community/README.md | 7 + docs/community/code-of-conduct.md | 9 + docs/community/developers.md | 112 +++++++++++++ docs/community/release-checklist.md | 251 ++++++++++++++++++++++++++++ 6 files changed, 389 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/community/README.md create mode 100644 docs/community/code-of-conduct.md create mode 100644 docs/community/developers.md create mode 100644 docs/community/release-checklist.md diff --git a/README.md b/README.md index 71e32cd..5dfac07 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ reduces complexity. [API Documentation](https://docs.rs/krator) +Looking for the developer guide? [Start here](docs/community/developers.md). + ## Examples [Moose Operator](crates/krator/examples) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..081d42f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# Krator documentation + +[API Documentation](https://docs.rs/krator) + +## Table of Contents + +- [Community Guides](community/README.md) teach you about the development + process for Krator and how you can contribute to the project. diff --git a/docs/community/README.md b/docs/community/README.md new file mode 100644 index 0000000..3148196 --- /dev/null +++ b/docs/community/README.md @@ -0,0 +1,7 @@ +# Community Guides + +Interested in contributing to Krator? Start here: + +- [Code of Conduct](code-of-conduct.md) +- [Developer Guide](developers.md) +- [Release Checklist](release-checklist.md) diff --git a/docs/community/code-of-conduct.md b/docs/community/code-of-conduct.md new file mode 100644 index 0000000..4fcc8c5 --- /dev/null +++ b/docs/community/code-of-conduct.md @@ -0,0 +1,9 @@ +# Code of Conduct + +This project has adopted the [Microsoft Open Source Code of +Conduct](https://opensource.microsoft.com/codeofconduct/). + +For more information see the [Code of Conduct +FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact +[opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional +questions or comments. diff --git a/docs/community/developers.md b/docs/community/developers.md new file mode 100644 index 0000000..4ff7b50 --- /dev/null +++ b/docs/community/developers.md @@ -0,0 +1,112 @@ +# Developer guide + +This guide explains how to set up your environment for developing Krator. + +## Prerequisites + +To build Krator, you will need + +- The latest stable version of Rust +- openssl (Or use the [`rustls-tls`](#building-without-openssl) feature) +- git + +If you want to test Krator, you will also require + +- A Kubernetes cluster. +- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) + +## Building + +We use `cargo` to build our programs: + +```console +$ cargo build +``` + +### Building without openssl + +If you are on a system that doesn't have OpenSSL (or has the incorrect version), +you have the option to build Krator using the Rustls project (Rust native TLS +implementation): + +```console +$ cargo build --no-default-features --features rustls-tls +``` + +The same flags can be passed to `cargo run` if you want to just [run](#running) +the project instead. + +#### Caveats + +The underlying dependencies for Rustls do not support certs with IP SANs +(subject alternate names). Because of this, the serving certs requested during +bootstrap will not work for local development options like minikube or KinD as +they do not have an FQDN + +### Building on WSL (Windows Subsystem for Linux) + +You can build Krator on WSL but will need a few prerequisites that aren't +included in the Ubuntu distro in the Microsoft Store: + +```console +$ sudo apt install build-essential libssl-dev pkg-config +``` + +**NOTE:** We've had mixed success developing Krator on WSL. It has been +successfully run on WSL2 using the WSL2-enabled Docker Kubernetes or Azure +Kubernetes. If you're on WSL1 you may be better off running in a full Linux VM +under Hyper-V. + +### Building on Windows + +We have support for building on Windows using PowerShell: + +```console +$ cargo build --no-default-features --features rustls-tls +``` + +**NOTE:** Windows builds use the `rustls` library, which means there are some +things to be aware of. See the [caveats](#caveats) section for more details + +## Running + +The included example with Krator is the [moose example](/krator/examples). + +``` +cargo run --example moose +``` + +## Testing + +Krator contains both unit tests and doc tests, and is routinely checked using +`clippy` and `rustfmt` as well. + +For unit tests: + +```console +$ cargo test --workspace +``` + +For doc tests: + +```console +$ cargo test --doc --all +``` + +For `clippy`: + +```console +$ cargo clippy --workspace +``` + +For `rustfmt`: + +```console +cargo fmt --all -- --check +``` + +## Creating your own Operators with Krator + +If you want to create your own Operator based on Krator, all you need to do is +implement an `Operator`. See the [moose example](/krator/examples/moose.rs) to +see how this is done. diff --git a/docs/community/release-checklist.md b/docs/community/release-checklist.md new file mode 100644 index 0000000..aab64f0 --- /dev/null +++ b/docs/community/release-checklist.md @@ -0,0 +1,251 @@ +# Release Checklist + +> If your experience deviates from this document, please document the changes +> to keep it up-to-date. + +This guide will guide you (redundancy added for purposes of punnery) on your +journey to release a new version of Krator. + +All releases will be of the form `vX.Y.Z` where `X` is the major version +number, `Y` is the minor version number and `Z` is the patch release number. +This project strictly follows [semantic versioning](https://semver.org/) so +following this step is critical. + +It is important to note that this document assumes that the git remote in your +repository that corresponds to is named +`upstream`. If yours is not (for example, if you've chosen to name it `origin` +or something similar instead), be sure to adjust the listed snippets for your +local environment accordingly. + +If you are not sure what your upstream remote is named, use a command like `git +remote -v` to find out. + +If you don't have an upstream remote, you can add one easily using the +following command: + +```console +git remote add upstream git@github.com:krator-rs/krator +``` + +## Step 0: determine what type of release you are cutting + +Major releases are for new feature additions and behavioral changes that break +backwards compatibility. Minor releases are for new feature additions that do +not break backwards compatibility. Patch releases are for bug fixes that do not +introduce any new features. + +There are two versions of the checklist: one for patch releases, and one for +major/minor releases. Follow the checklist that best applies below. + +## Checklist for major and minor releases + +Follow this checklist if you are cutting a major release (vX.0.0) or a minor +release (vX.Y.0): + +1. set up your environment +1. increment the version number +1. finalize the release and write the release notes + +In this checklist, we are going to reference a few environment variables which +you will want to set for convenience. + +For major and minor releases, set the following environment variables, changing +the values of `$MAJOR_RELEASE_NUMBER`, `$MINOR_RELEASE_NUMBER`, and +`$RELEASE_CANDIDATE_NUMBER` accordingly: + +```console +export MAJOR_RELEASE_NUMBER="0" +export MINOR_RELEASE_NUMBER="1" +export RELEASE_NAME="v${MAJOR_RELEASE_NUMBER}.${MINOR_RELEASE_NUMBER}.0" +``` + +Now that we know we are going to cut a major or a minor release, we will need to +bump the project's Cargo.toml as well as any crates that have been updated this +release. + +Open a new pull request against Krator, bumping the version fields in +Cargo.toml: + +- + +Use the following commands to create the commit: + +```console +git add . +git commit -m "bump version to $RELEASE_NAME" +``` + +Wait until the pull request has been merged into `main` before proceeding. + +After the pull request has been merged, create a new tag from upstream's +`main` branch. + +```console +git fetch upstream main +git checkout upstream/main +git tag --annotate "${RELEASE_NAME}" --message "Krator release ${RELEASE_NAME}" +``` + +Double-check one last time to make sure everything is in order, then finally +push the release tag. + +```console +git push upstream $RELEASE_NAME +``` + +It is usually more beneficial to the end-user if the release notes are +hand-written by a human being/marketing team/dog, so we'll go ahead and write +up the release notes. + +If you're releasing a major/minor release, listing notable user-facing features +is usually sufficient. For patch releases, do the same, but make note of the +symptoms causing the original issue, who may be affected, and how the patch +mitigates the issue. + +it should look like this: + +```markdown +## Krator vX.Y.Z + +Krator vX.Y.Z is a feature release. This release, we focused on . Users are encouraged to upgrade for the best experience. + +## Notable features/changes + +- TLS bootstrapping support has been added +- Improved error handling for the Kubernetes API + +## Breaking changes + +No known breaking changes were introduced this release. + +## Known issues/missing features + +- Needs more cowbell +- I gotta have more cowbell! +``` + +Feel free to bring in your own personality into the release notes; it's nice +for people to think we're not all robots. :) + +Double check the URLs are correct. Once finished, go into GitHub and edit the +release notes for the tagged release with the notes written here. + +It is now worth getting other people to take a look at the release notes before +the release is published. It is always beneficial as it can be easy to miss +something. + +For pre-v1.0 releases, make sure to check the checkbox that says "This is a +pre-release" to notify users that this release is identified as non-production +ready. + +When you are ready to go, hit `publish`, and you're done. + +## Checklist for patch releases + +Follow this checklist if you are cutting a patch release (vX.Y.Z). The process +is largely the same as cutting a major/minor release, but with a few +differences. + +1. set up your environment +1. increment the version number +1. cherry-pick fixes +1. finalize the release and write the release notes + +In this checklist, we are going to reference a few environment variables which +you will want to set for convenience. + +For patch releases, set the following environment variables: + +```console +export MAJOR_RELEASE_NUMBER="0" +export MINOR_RELEASE_NUMBER="1" +export PATCH_RELEASE_NUMBER="1" +export PREVIOUS_PATCH_RELEASE_NUMBER="0" +export RELEASE_NAME="v${MAJOR_RELEASE_NUMBER}.${MINOR_RELEASE_NUMBER}.${PATCH_RELEASE_NUMBER}" +export PREVIOUS_RELEASE_NAME="v${MAJOR_RELEASE_NUMBER}.${MINOR_RELEASE_NUMBER}.${PREVIOUS_PATCH_RELEASE_NUMBER}" +export RELEASE_BRANCH_NAME="release-${MAJOR_RELEASE_NUMBER}.${MINOR_RELEASE_NUMBER}.${PATCH_RELEASE_NUMBER}" +``` + +Now that we know we are going to cut a patch release, we will need to bump the +project's Cargo.toml as well as any crates that have been updated this release. + +Open a new pull request against Krator, bumping the version fields in +Cargo.toml: + +- + +Use the following commands to create the commit: + +```console +git add . +git commit -m "bump version to $RELEASE_NAME" +``` + +Wait until the pull request has been merged into `main` before proceeding. + +After the pull request has been merged, checkout the previous tag from upstream +and use it to create a new branch: + +```console +git fetch upstream --tags +git checkout $PREVIOUS_RELEASE_NAME +git checkout -b $RELEASE_BRANCH_NAME +``` + +Once that's done, make sure to cherry-pick the fixes as well as the version +bump from the previous step into this branch: + +```console +git cherry-pick -x +``` + +If anyone is available, let others peer-review the branch before continuing to +ensure that all the proper fixes have been merged into the release branch. + +When you're finally happy with the quality of the release branch, you can move +on and create the tag. Double-check one last time to make sure everything is in +order, then finally push the release tag. + +```console +git tag --annotate "${RELEASE_NAME}" --message "Krator release ${RELEASE_NAME}" +git push upstream $RELEASE_NAME +``` + +It is usually more beneficial to the end-user if the release notes are +hand-written by a human being/marketing team/dog, so we'll go ahead and write +up the release notes. + +For patch releases, make note of the symptoms causing the original issue(s), +who may be affected, and how the patch(es) mitigate the issue(s). + +it should look like this: + +```markdown +## Krator vX.Y.Z + +Krator vX.Y.Z is a patch release, fixing an issue where . + +This patch fixes this issue by . + +Users are encouraged to upgrade for the best experience. + +## Breaking changes + +No known breaking changes were introduced this release. + +``` + +Double check the URLs are correct. Once finished, go into GitHub and edit the +release notes for the tagged release with the notes written here. + +It is now worth getting other people to take a look at the release notes before +the release is published. It is always beneficial as it can be easy to miss +something. + +For pre-v1.0 releases, make sure to check the checkbox that says "This is a +pre-release" to notify users that this release is identified as non-production +ready. + +When you are ready to go, hit `publish`, and you're done.