Merge pull request #227 from Nordix/docs-mael

📖 Add developer documentation regarding version and releases

CONTRIBUTING.md

@@ -1,11 +1,116 @@
 # 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)
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [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)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Certificate of Origin
 
 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 <your Github ID>` comment on the issue or pull request.

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
+
+<!-- markdownlint-disable -->
+## TL;DR:
+<!-- markdownlint-restore -->
+
+- 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, happen 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.  In some cases, it may
+be necessary to open PRs for bugfixes directly against stable branches, but
+this should generally be avoided.
+
+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 bug fix in with
+a breaking change, it's generally encouraged to submit the bug fix
+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`.
+
+<!-- markdownlint-disable -->
+## Why don't we...
+<!-- markdownlint-restore -->
+
+### 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.