diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..3495666e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,220 @@ +# Contributing Guidelines + + + +- [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) +- [ADRs (Architectural Decision Records)](#adrs-architectural-decision-records) + - [Process](#process) + + + +Thank you for taking the time to contribute to `rancher-turtles` project :heart: + +Improvements to all areas of the project; from code, to documentation; +from bug reports to feature design 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 rancher-turtle's 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]! + + (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 issue: [bug reports](#bug-report-guide), [feature requests](#feature-request-guide). 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? 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). + +# 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 issue`](https://github.com/rancher-sandbox/rancher-turtles/labels/good%20first%20issue) + should be accessible to folks new to the repo, 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/rancher-sandbox/rancher-turtles/labels/help%20wanted) + are for those a little more familiar with the code base, but should still be accessible enough + to newcomers. + +- All other issues labelled `kind/` or `area/` are also up for grabs, but + are likely to require a fair amount of context. + +## Developing rancher-turtles + +Check out a dedicated [notes](https://github.com/rancher-sandbox/rancher-turtles#development-setup) section in the rancher-turtles repository. + +## 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 + ``` +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 othe + +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 + + + + + +