Add docs version 0.5

versioned_docs/version-0.5/contributing/development.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 2
+---
+
+# Development setup
+
+## Prerequisites:
+
+- [kind](https://kind.sigs.k8s.io/)
+- [helm](https://helm.sh/)
+- [clusterctl](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl)
+- [tilt](https://tilt.dev/)
+
+
+## Create a local development environment
+
+1. Clone the [Rancher Turtles](https://github.com/rancher-sandbox/rancher-turtles) repository locally
+
+2. Create **tilt-settings.yaml**:
+
+```yaml
+{
+    "k8s_context": "k3d-rancher-test",
+    "default_registry": "ghcr.io/rancher-turtles-dev",
+    "debug": {
+        "turtles": {
+            "continue": true,
+            "port": 40000
+        }
+    }
+}
+```
+
+3. Open a terminal in the root of the Rancher Turtles repository
+4. Run the following:
+
+```bash
+make dev-env
+
+# Or if you want to use a custom hostname for Rancher
+RANCHER_HOSTNAME=my.customhost.dev make dev-env
+```
+
+5. When tilt has started, open a new terminal and start ngrok or inlets
+
+```bash
+kubectl port-forward --namespace cattle-system svc/rancher 10000:443
+ngrok http https://localhost:10000
+```
+
+## What happens when you run `make dev-env`?
+
+1. A [kind](https://kind.sigs.k8s.io/) cluster is created with the following [configuration](https://github.com/rancher-sandbox/rancher-turtles/blob/main/scripts/kind-cluster-with-extramounts.yaml).
+1. [Cert manager](https://cert-manager.io/) is installed on the cluster, which is a requirement for running `Rancher turtes` extension.
+1. `clusterctl` is used to bootstrap CAPI components onto the cluster, and a default configuration includes: core Cluster API controller, Kubeadm bootstrap and control plane providers, Docker infrastructure provider.
+1. `Rancher manager` is installed using helm.
+1. `tilt up` is run to start the development environment.

versioned_docs/version-0.5/contributing/guidelines.md

@@ -0,0 +1,291 @@
+---
+sidebar_position: 1
+---
+# Guidelines
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [How to get involved?](#how-to-get-involved)
+- [Submitting PRs](#submitting-prs)
+  - [Choosing something to work on](#choosing-something-to-work-on)
+  - [Developing rancher-turtles](#developing-rancher-turtles)
+  - [Asking for help](#asking-for-help)
+  - [PR submission guidelines](#pr-submission-guidelines)
+    - [Commit message formatting](#commit-message-formatting)
+- [Opening Issues](#opening-issues)
+- [How the Maintainers process contributions](#how-the-maintainers-process-contributions)
+  - [Prioritizing issues](#prioritizing-issues)
+  - [Reviewing PRs](#reviewing-prs)
+- [ADRs (Architectural Decision Records)](#adrs-architectural-decision-records)
+  - [Process](#process)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+Thank you for taking the time to contribute to Rancher CAPI extension [projects](https://github.com/rancher-sandbox?q=rancher-turtles&type=all&language=&sort=) :heart:
+
+Improvements to all areas of the project; from code, to documentation;
+from bug reports to feature design and UI enhancement are gratefully welcome.
+This guide should cover all aspects of how to interact with the project
+and how to get involved in development as smoothly as possible.
+
+Reading docs is often tedious, so let's put the important contributing rule
+right at the top: **Always be kind!**
+
+Looking forward to seeing your contributions in the repo! :sparkles:
+
+## How to get involved?
+
+We'd love to accept your patches in pretty much all areas of projects development!
+
+If you’re a new to the project and want to help, but don’t know where to start, here is a non-exhaustive list of ways you can help out:
+
+1. Submit a [Pull Request](#submitting-prs) :rocket:
+
+    Beyond fixing bugs and submitting new features, there are other things you can submit
+    which, while less flashy, will be deeply appreciated by all who interact with the codebase:
+
+      - Extending test coverage!
+      - Refactoring!
+      - Reviewing and updating [documentation][user-docs]!
+      - Adding a new UI functionality!
+
+   (See also [Choosing something to work on](#choosing-something-to-work-on) below.)
+1. Open an [issue](#opening-issues) :interrobang:
+
+    We have 2 forms of issues: bug reports and feature requests. If you are not sure which category you need, just make the best guess and provide as much information as possible.
+
+1. Interested in helping to improve:
+
+- Rancher CAPI extension backend? Chime in on [`bugs`](https://github.com/rancher-sandbox/rancher-turtles/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fbug+) or
+    [`help wanted` issues](https://github.com/rancher-sandbox/rancher-turtles/labels/help-wanted).
+    If you are seeking to take on a bigger challenge or a more experienced contributor, check out [`feature requests`](https://github.com/rancher-sandbox/rancher-turtles/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Ffeature).
+- extension UI? Take a look at [`open`](https://github.com/rancher-sandbox/rancher-turtles-ui/issues) or
+    [`help wanted` issues](https://github.com/rancher-sandbox/rancher-turtles-ui/labels/help-wanted).
+- maybe, user-docs? :nerd_face: Then, jump straight into [`open` issues](https://github.com/rancher-sandbox/rancher-turtles-docs/issues) in the docs repository.
+
+## Opening Issues
+
+These guides aim to help you write issues in a way which will ensure that they are processed
+as quickly as possible.
+
+_See below for [how issues are prioritized](#prioritizing-issues)_.
+
+**General rules**:
+
+1. Before opening anything, take a good look through existing issues.
+
+1. More is more: give as much information as it is humanly possible to give.
+  Highly detailed issues are more likely to be picked up because they can be prioritized and
+  scheduled for work faster. They are also more accessible
+  to the community, meaning that you may not have to wait for the core team to get to it.
+
+1. Please do not open an issue with a description that is **just** a link to another issue,
+  a link to a slack conversation, a quote from either one of those, or anything else
+  equally opaque. This raises the bar for entry and makes it hard for the community
+  to get involved. Take the time to write a proper description and summarise key points.
+
+1. Take care with formatting. Ensure the [markdown is tidy](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/getting-started-with-writing-and-formatting-on-github),
+  use [code blocks](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/creating-and-highlighting-code-blocks) etc etc.
+  The faster something can be read, the faster it can be dealt with.
+
+1. Keep it civil. Yes, it is annoying when things don't work, but it is way more fun helping out
+  someone who is not... the worst. Remember that conversing via text exacerbates
+  everyone's negativity bias, so throw in some emoji when in doubt :+1: :smiley: :rocket: :tada:.
+
+## Submitting PRs
+
+### Choosing something to work on
+
+If you are here to ask for help or request some new behaviour, this
+is the section for you. We have curated a set of issues for anyone who simply
+wants to build up their open-source cred :muscle:.
+
+- Issues labelled [`good first issues`](https://github.com/search?q=org%3Agithub%2Francher-sandbox+repo%3Arancher-sandbox%2Francher-turtles+repo%3Arancher-sandbox%2Francher-turtles-ui+repo%3Arancher-sandbox%2Francher-turtles-docs+is%3Aopen+label%3A%22good+first+issue%22+&type=issues&ref=advsearch)
+  should be accessible to folks new to the repos, as well as to open source in general.
+
+  These issues should present a low/non-existent barrier to entry with a thorough description,
+  easy-to-follow reproduction (if relevant) and enough context for anyone to pick up.
+  The objective should be clear, possibly with a suggested solution or some pseudocode.
+  If anything similar has been done, that work should be linked.
+
+  If you have come across an issue tagged with `good first issue` which you think you would
+  like to claim but isn't 100% clear, please ask for more info! When people write issues
+  there is a _lot_ of assumed knowledge which is very often taken for granted. This is
+  something we could all get better at, so don't be shy in asking for what you need
+  to do great work :smile:.
+
+  See more on [asking for help](#asking-for-help) below!
+
+- [`help wanted` issues](https://github.com/search?q=org%3Agithub%2Francher-sandbox+repo%3Arancher-sandbox%2Francher-turtles+repo%3Arancher-sandbox%2Francher-turtles-ui+repo%3Arancher-sandbox%2Francher-turtles-docs+is%3Aopen+label%3A%22help+wanted%22+&type=issues&ref=advsearch)
+  are for those a little more familiar with the code base, but should still be accessible enough
+  to newcomers.
+
+- All other issues labelled `kind/<x>` or `area/<x>` are also up for grabs, but
+  are likely to require a fair amount of context.
+
+### Developing rancher-turtles
+
+Check out the dedicated [notes](./development.md) on getting started with development.
+
+### Asking for help
+
+If you need help at any stage of your work, please don't hesitate to ask!
+
+- To get more detail on the issue you have chosen, it is a good idea to start by asking
+  whoever created it to provide more information.
+
+- If you are struggling with something while working on your PR, or aren't quite
+  sure of your approach, you can open a [draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
+  (prefix the title with `WIP:`) and explain what you are thinking.
+
+### PR submission guidelines
+
+1. Fork the desired repo, develop and test your code changes.
+1. Push your changes to the branch on your fork and submit a pull request to the original repository
+against the `main` branch.
+
+```bash
+git push <remote-name> <feature-name>
+```
+
+1. Submit a pull request.
+    1. All code PR must be labeled with one of
+        - ⚠️ (`:warning:`, major or breaking changes)
+        - ✨ (`:sparkles:`, feature additions)
+        - 🐛 (`:bug:`, patch and bugfixes)
+        - 📖 (`:book:`, documentation or proposals)
+        - 🌱 (`:seedling:`, minor or other)
+
+Where possible, please squash your commits to ensure a tidy and descriptive history.
+
+If your PR is still a work in progress, please open a [Draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
+and prefix your title with the word `WIP`. When your PR is ready for review, you
+can change the title and remove the Draft setting.
+
+We recommend that you regularly rebase from `main` of the original repo to keep your
+branch up to date.
+
+In general, we will merge a PR once a maintainer has reviewed and approved it.
+Trivial changes (e.g., corrections to spelling) may get waved through.
+For substantial changes, more people may become involved, and you might get asked to resubmit the PR or divide the changes into more than one PR.
+
+#### Commit message formatting
+
+_For more on how to write great commit messages, and why you should, check out
+[this excellent blog post](https://chris.beams.io/posts/git-commit/)._
+
+We follow a rough convention for commit messages that is designed to answer three
+questions: what changed, why was the change made, and how did you make it.
+
+The subject line should feature the _what_ and
+the body of the commit should describe the _why_ and _how_.
+If you encountered any weirdness along the way, this is a good place
+to note what you discovered and how you solved it.
+
+The format can be described more formally as follows:
+
+```text
+<short title for what changed>
+<BLANK LINE>
+<why this change was made and what changed>
+<BLANK LINE>
+<any interesting details>
+<footer>
+```
+
+The first line is the subject and should be no longer than 70 characters, the
+second line is always blank, and other lines should be wrapped at a max of 80 characters.
+This allows the message to be easier to read on GitHub as well as in various git tools.
+
+There is a template recommend for use [here](https://gist.github.com/yitsushi/656e68c7db141743e81b7dcd23362f1a).
+
+## How the Maintainers process contributions
+
+### Prioritizing issues
+
+The core team regularly processes incoming issues. There may be some delay over holiday periods.
+
+Every issue will be assigned a `priority/<x>` label. The levels of priorities are:
+
+- [`critical-urgent`](https://github.com/rancher-sandbox/rancher-turtles/labels/priority%2Fcritical-urgent): These are time sensitive issues which should be picked up immediately.
+  If an issue labelled `critical` is not assigned or being actively worked on,
+  someone is expected to drop what they're doing immediately to work on it.
+  This usually means the core team, but community members are welcome to claim
+  issues at any priority level if they get there first. _However, given the pressing
+  timeframe, should a non-core contributor request to be assigned to a `critical` issue,
+  they will be paired with a core team-member to manage the tracking, communication and release of any fix
+  as well as to assume responsibility of all progess._
+
+- [`important-soon`](https://github.com/rancher-sandbox/rancher-turtles/labels/priority%2Fimportant-soon): Must be assigned as soon as capacity becomes available.
+  Ideally something should be delivered in time for the next release.
+
+- [`important-longterm`](https://github.com/rancher-sandbox/rancher-turtles/labels/priority%2Fimportant-longterm): Important over the long term, but may not be currently
+  staffed and/or may require multiple releases to complete.
+
+- [`backlog`](https://github.com/rancher-sandbox/rancher-turtles/labels/priority%2Fbacklog): There appears to be general agreement that this would be good to have,
+  but we may not have anyone available to work on it right now or in the immediate future.
+  PRs are still very welcome, although it might take a while to get them reviewed if
+  reviewers are fully occupied with higher priority issues, for example immediately before a release.
+
+These priority categories have been inspired by [the Kubernetes contributing guide](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md).
+
+Other labels include:
+
+- [`adr-required`](https://github.com/rancher-sandbox/rancher-turtles/labels/adr-required):
+  Indicates that the issue or PR contains a decision that needs to be documented in a [ADR](#adrs-architectural-decision-records) _before_
+  it can be worked on.
+
+- [`needs-investigation`](https://github.com/rancher-sandbox/rancher-turtles/labels/needs-investigation):  There is currently insufficient information to either categorize properly,
+  or to understand and implement a solution. This could be because the issue opener did
+  not provide enough relevant information, or because more in-depth research is required
+  before work can begin.
+
+### Reviewing PRs
+
+The core team aims to clear the PR queue as quickly as possible. Community members
+should also feel free to keep an eye on things and provide their own thoughts and expertise.
+
+High-value and/or high priority contributions will be processed as quickly as possible,
+while lower priority or nice-to-have things may take a little longer to get approved.
+
+To help facilitate a smoother and faster review, follow the guidelines [above](#pr-submission-guidelines).
+Submissions which do not meet standards will be de-prioritised for review.
+
+## ADRs (Architectural Decision Records)
+
+:::note
+Please feel free to skip [this](#adrs-architectural-decision-records) and [sub-section](#process) below, since they are only relevant to the [rancher-turtles](https://github.com/rancher-sandbox/rancher-turtles) repository.
+:::
+
+Any impactful decisions to the architecture, design, development and behaviour
+of rancher-turtles must be recorded in the form of an [ADR](https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/).
+
+A template can be found at [`docs/adr/0000-template.md`][adr-template] of the repo,
+with numerous examples of completed records in the same directory.
+
+Contributors are also welcome to backfill ADRs if they are found to be missing.
+
+### Process
+
+1. Start a new [discussion](https://github.com/rancher-sandbox/rancher-turtles/discussions/new?category=adr) using the `ADR` category.
+
+1. Choose an appropriate clear and concise title (e.g. `ADR: Implement X in Go`).
+
+1. Provide a context of the decision to be made. Describe
+  the various options, if more than one, and explain the pros and cons. Highlight
+  any areas which you would like the reviewers to pay attention to, or those on which
+  you would specifically like an opinion.
+
+1. Tag in the [maintainers](https://github.com/rancher-sandbox/rancher-turtles/blob/main/CODEOWNERS) as the "Deciders", and invite them to
+  participate and weigh in on the decision and its consequences.
+
+1. Once a decision has been made, open a PR adding a new ADR to the [directory](https://github.com/rancher-sandbox/rancher-turtles/blob/main/docs/adr).
+  Copy and complete the [template][adr-template];
+    - Increment the file number by one
+    - Set the status as "Accepted"
+    - Set the deciders as those who approved the discussion outcome
+    - Summarise the decision and consequences from the discussion thread
+    - Link back to the discussion from the ADR doc
+
+[user-docs]: https://rancher-sandbox.github.io/rancher-turtles-docs/
+[adr-template]: https://github.com/rancher-sandbox/rancher-turtles/blob/main/docs/adr/0000-template.md

versioned_docs/version-0.5/contributing/intro.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 0
+---
+
+# Introduction
+
+Everything you need to know about contributing to Rancher Turtles.