diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddff0e75b..5e2ba9a46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,21 @@ # How to Contribute Metal3 projects are [Apache 2.0 licensed](LICENSE) and accept contributions via -GitHub pull requests. +GitHub pull requests. Those guidelines are the same as the +[Cluster API guidelines](https://github.com/kubernetes-sigs/cluster-api/blob/master/CONTRIBUTING.md) + + + + +- [Certificate of Origin](#certificate-of-origin) +- [Finding Things That Need Help](#finding-things-that-need-help) +- [Contributing a Patch](#contributing-a-patch) +- [Backporting a Patch](#backporting-a-patch) + - [Merge Approval](#merge-approval) + - [Google Doc Viewing Permissions](#google-doc-viewing-permissions) + - [Issue and Pull Request Management](#issue-and-pull-request-management) + + ## Certificate of Origin @@ -9,3 +23,94 @@ By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the [DCO](DCO) file for details. + +## Finding Things That Need Help + +If you're new to the project and want to help, but don't know where to start, we +have a semi-curated list of issues that +should not need deep knowledge of the system. [Have a look and see if anything +sounds interesting](https://github.com/metal3-io/cluster-api-provider-baremetal/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). +Alternatively, read some of the docs on other controllers and try to write your +own, file and fix any/all issues that come up, including gaps in documentation! + +## Contributing a Patch + +1. If you haven't already done so, sign a Contributor License Agreement (see + details above). +1. Fork the desired repo, develop and test your code changes. +1. Submit a pull request. + +All code PR must be labeled with one of + +- ⚠️ (:warning:, major or breaking changes) +- ✨ (:sparkles:, minor or feature additions) +- 🐛 (:bug:, patch and bugfixes) +- 📖 (:book:, documentation or proposals) +- 🏃 (:running:, other) + +All changes must be code reviewed. Coding conventions and standards are +explained in the official [developer +docs](https://github.com/kubernetes/community/tree/master/contributors/devel). +Expect reviewers to request that you +avoid common [go style +mistakes](https://github.com/golang/go/wiki/CodeReviewComments) in your PRs. + +## Backporting a Patch + +Cluster API maintains older versions through `release-X.Y` branches. We accept +backports of bug fixes to the most recent +release branch. For example, if the most recent branch is `release-0.2`, and the +`master` branch is under active +development for v0.3.0, a bug fix that merged to `master` that also affects +`v0.2.x` may be considered for backporting +to `release-0.2`. We generally do not accept PRs against older release branches. + +## Breaking Changes + +Breaking changes are generally allowed in the `master` branch, as this is the +branch used to develop the next minor release of Cluster API. + +There may be times, however, when `master` is closed for breaking changes. This +is likely to happen as we near the release of a new minor version. + +Breaking changes are not allowed in release branches, as these represent minor +versions that have already been released. +These versions have consumers who expect the APIs, behaviors, etc. to remain +stable during the life time of the patch stream for the minor release. + +Examples of breaking changes include: + +- Removing or renaming a field in a CRD +- Removing or renaming a CRD +- Removing or renaming an exported constant, variable, type, or function +- Updating the version of critical libraries such as controller-runtime, + client-go, apimachinery, etc. +- Some version updates may be acceptable, for picking up bug fixes, but + maintainers must exercise caution when reviewing. + +There may, at times, need to be exceptions where breaking changes are allowed in +release branches. These are at the discretion of the project's maintainers, and +must be carefully considered before merging. An example of an allowed +breaking change might be a fix for a behavioral bug that was released in an +initial minor version (such as `v0.3.0`). + +### Merge Approval + +Please see the [Kubernetes community document on pull +requests](https://git.k8s.io/community/contributors/guide/pull-requests.md) for +more information about the merge process. + +### Google Doc Viewing Permissions + +To gain viewing permissions to google docs in this project, please join the +[metal3-dev](https://groups.google.com/forum/#!forum/metal3-dev) google +group. + +### Issue and Pull Request Management + +Anyone may comment on issues and submit reviews for pull requests. However, in +order to be assigned an issue or pull request, you must be a member of the +[Metal3-io organization](https://github.com/metal3-io) GitHub organization. + +Metal3 maintainers can assign you an issue or pull request by leaving a +`/assign ` comment on the issue or pull request. diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 000000000..ad01ebff9 --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,178 @@ +# Versioning + +Those guidelines are coming from +[Cluster API](https://github.com/kubernetes-sigs/cluster-api/blob/master/VERSIONING.md) +as we try to follow closely the release process + + +## TL;DR: + + +- We follow [Semantic Versioning (semver)](https://semver.org/). +- We try to follow Cluster API release cadence +- The cadence is subject to change if necessary, refer to the + [Milestones](https://github.com/kubernetes-sigs/cluster-api/milestones) page + for up-to-date information. +- The _master_ branch is where development happens, this might include breaking + changes. +- The _release-X_ branches contain stable, backward compatible code. A new + _release-X_ branch is created at every major (X) release. + +## Overview + +Cluster API follows [Semantic Versioning](https://semver.org). +I'd recommend reading the aforementioned link if you're not familiar, +but essentially, for any given release X.Y.Z: + +- an X (*major*) release indicates a set of backwards-compatible code. + Changing X means there's a breaking change. + +- a Y (*minor*) release indicates a minimum feature set. Changing Y means + the addition of a backwards-compatible feature. + +- a Z (*patch*) release indicates minimum set of bugfixes. Changing + Z means a backwards-compatible change that doesn't add functionality. + +*NB*: If the major release is `0`, any minor release may contain breaking +changes. + +These guarantees extend to all code exposed in public APIs of +Cluster API Provider Baremetal. This includes code both in Cluster API Provider +Baremetal itself, *plus types from dependencies in public APIs*. Types and +functions not in public APIs are not considered part of the guarantee. + +In order to easily maintain the guarantees, we have a couple of processes +that we follow. + +## Branches + +Cluster API Provider Baremetal contains two types of branches: the *master* +branch and *release-X* branches. + +The *master* branch is where development happens. All the latest and +greatest code, including breaking changes, happens on master. + +The *release-X* branches contain stable, backwards compatible code. Every +major (X) release, a new such branch is created. It is from these +branches that minor and patch releases are tagged. If some cases, it may +be necessary open PRs for bugfixes directly against stable branches, but +this should generally not be the case. + +The maintainers are responsible for updating the contents of this branch; +generally, this is done just before a release using release tooling that +filters and checks for changes tagged as breaking (see below). + +## PR Process + +Every PR should be annotated with an icon indicating whether it's +a: + +- Breaking change: :warning: (`:warning:`) +- Non-breaking feature: :sparkles: (`:sparkles:`) +- Patch fix: :bug: (`:bug:`) +- Docs: :book: (`:book:`) +- Infra/Tests/Other: :running: (`:running:`) + +You can also use the equivalent emoji directly, since GitHub doesn't +render the `:xyz:` aliases in PR titles. + +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. + +### Commands and Workflow + +Cluster API Provider Baremetal follows the standard Kubernetes workflow: any PR +needs `lgtm` and `approved` labels, PRs authors must have signed the CNCF CLA, +and PRs must pass the tests before being merged. See [the contributor +docs](https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#the-testing-and-merge-workflow) +for more info. + +We use the same priority and kind labels as Kubernetes. See the labels +tab in GitHub for the full list. + +The standard Kubernetes comment commands should work in +Cluster API Provider Baremetal. See [Prow](https://prow.k8s.io/command-help) +for a command reference. + +## Release Process + +Minor and patch releases are generally done immediately after a feature or +bugfix is landed, or sometimes a series of features tied together. + +Minor releases will only be tagged on the *most recent* major release +branch, except in exceptional circumstances. Patches will be backported +to maintained stable versions, as needed. + +Major releases are done shortly after a breaking change is merged -- once +a breaking change is merged, the next release *must* be a major revision. +We don't intend to have a lot of these, so we may put off merging breaking +PRs until a later date. + +### Exact Steps + +Refer to the [releasing document](./docs/releasing.md) for the exact steps. + +### Breaking Changes + +Try to avoid breaking changes. They make life difficult for users, who +have to rewrite their code when they eventually upgrade, and for +maintainers/contributors, who have to deal with differences between master +and stable branches. + +That being said, we'll occasionally want to make breaking changes. They'll +be merged onto master, and will then trigger a major release (see [Release +Process](#release-process)). Because breaking changes induce a major +revision, the maintainers may delay a particular breaking change until +a later date when they are ready to make a major revision with a few +breaking changes. + +If you're going to make a breaking change, please make sure to explain in +detail why it's helpful. Is it necessary to cleanly resolve an issue? +Does it improve API ergonomics? + +Maintainers should treat breaking changes with caution, and evaluate +potential non-breaking solutions (see below). + +Note that API breakage in public APIs due to dependencies will trigger +a major revision, so you may occasionally need to have a major release +anyway, due to changes in libraries like `k8s.io/client-go` or +`k8s.io/apimachinery`. + + +## Why don't we... + + +### Use "next"-style branches + +Development branches: + +- don't win us much in terms of maintenance in the case of breaking + changes (we still have to merge/manage multiple branches for development + and stable) + +- can be confusing to contributors, who often expect master to have the + latest changes. + +### Never break compatibility + +Never doing a new major release could be an admirable goal, but gradually +leads to API cruft. + +Since one of the goals of Cluster API is to be a friendly and +intuitive API, we want to avoid too much API cruft over time, and +occaisonal breaking changes in major releases help accomplish that goal. + +Furthermore, our dependency on Kubernetes libraries makes this difficult +(see below) + +### Always assume we've broken compatibility + +*a.k.a. k8s.io/client-go style* While this makes life easier (a bit) for +maintainers, it's problematic for users. While breaking changes arrive sooner, +upgrading becomes very painful. + +Furthermore, we still have to maintain stable branches for bugfixes, so +the maintenance burden isn't lessened by a ton.