Guidelines

Thank you for taking the time to contribute to Rancher CAPI extension projects.

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!

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

    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!

    • Adding a new UI functionality!

    (See also Choosing something to work on below.)

  2. Open an issue

    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.

  3. Interested in helping to improve:

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.

General rules:

  1. Before opening anything, take a good look through existing issues.

  2. 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.

  3. 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.

  4. Take care with formatting. Ensure the markdown is tidy, use code blocks etc etc. The faster something can be read, the faster it can be dealt with.

  5. 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.

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.

  • Issues labelled good first issues 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.

    See more on asking for help below!

  • help wanted issues 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 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 (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.

  2. Push your changes to the branch on your fork and submit a pull request to the original repository against the main branch.

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 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.

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:

<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.

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: 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: Must be assigned as soon as capacity becomes available. Ideally something should be delivered in time for the next release.

  • important-longterm: Important over the long term, but may not be currently staffed and/or may require multiple releases to complete.

  • backlog: 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.

Other labels include:

  • adr-required: Indicates that the issue or PR contains a decision that needs to be documented in a ADR before it can be worked on.

  • 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. Submissions which do not meet standards will be de-prioritised for review.

ADRs (Architectural Decision Records)

Please feel free to skip this and sub-section below, since they are only relevant to the 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.

A template can be found at docs/adr/0000-template.md 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 using the ADR category.

  2. Choose an appropriate clear and concise title (e.g. ADR: Implement X in Go).

  3. 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.

  4. Tag in the maintainers as the "Deciders", and invite them to participate and weigh in on the decision and its consequences.

  5. Once a decision has been made, open a PR adding a new ADR to the directory. Copy and complete the 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