Skip to content

Latest commit

 

History

History
701 lines (494 loc) · 31.4 KB

CONTRIBUTING.md

File metadata and controls

701 lines (494 loc) · 31.4 KB
Raw

eksctl ❤️s your contributions

Thank you for taking the time to contribute to eksctl.

We gratefully welcome improvements to all areas; from code, to documentation; from bug reports to feature design.

This guide should cover all aspects of how to interact with the project and how to get involved in development as smoothly as possible.

If we have missed anything you think should be included, or if anything is not clear, we also accept contributions to this contribution doc 😄.

For information on how to get in touch, or how the project is run, please see the Community page.

(If you are a Maintainer, head over to the Maintainer's guide.)

Reading docs is often tedious, so we'll put our most important contributing rule right at the top: Always be kind!

Looking forward to seeing you in the repo! ✨

Table of Contents

Legal bits

License

eksctl is Apache 2.0 licensed.

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. No action from you is required, but it's a good idea to see the DCO file for details before you start contributing code to eksctl.

Where can I get involved?

We are happy to see people in pretty much all areas of eksctl's development. Here is a non-exhaustive list of ways you can help out:

  1. Open a PR.

    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:

    • Backfilling tests!
    • Refactoring!
    • Reviewing and updating documentation!

    (See also Choosing something to work on below.)

  2. Open an issue. ⁉️

    We have 3 forms of issue: bug reports, feature requests and help requests. If you are not sure which category you need, just make the best guess and provide as much information as possible.

  3. Help out others in the eksctl slack channel. 🆘

  4. Chime in on bugs, feature requests and asks for help. 💭

  5. Dig into some needs-investigation issues 🕵️

  6. Get involved in some PR reviews. 🤓

  7. Review old issues; poke or suggest closing ones which are stale or follow up those which still look good. 💬

  8. Think deeply about the future of eksctl, then talk about it. 🔮

The eksctl roadmap

eksctl roadmap can be found here.

This is the general long game we are playing. Contributions which steer us further towards these overarching goals will be enthusiastically welcomed, while contributions which are orthogonal or leading in another direction will likely be rejected.

For bonus points, please highlight how feature requests/PRs fit into the roadmap when you can!

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 simply 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 👍 😃 🚀 🎉.

Dedicated guides:

Bug report guide

We hope to get to bug reports within a couple of working days, but please wait for at least 7 before nudging. (Unless it is a super critical end-of-the world bug, then by all means make some noise 📢.)

Below are the criteria we like our bug reports to cover in order to gather the bare minimum of information. Add more that what is asked for if you can 😃.

  1. Search existing issues. If something similar already exists, and is still open, please contribute to the discussion there.

  2. Bump to the latest version of eksctl to see whether your issue has already been fixed.

  3. Write a concise and descriptive title, like you would a commit message, something which others can easily find when doing step 1 above.

  4. Detail what it was that you were trying to do and what you expected would happen. Give some background information around what you have already done to your cluster, any custom configuration etc. With sufficient information you can pre-empt any questions others may have. This should cut out some obvious back-and-forth and help get people to the heart of the issue quickly.

  5. Explain what actually happened. Provide the relevant error message and key logs.

  6. Provide a reproduction, for example the exact command or a yaml file (sensitive info redacted). Please try to reduce your reproduction to the minimal necessary to help whoever is helping you get to the broken state without needing to recreate your entire environment.

  7. If possible, reproduce the issue with logging verbosity set to at least 4 (-v=4), if you have not already done so. Ensure logs are formatted with code blocks. If they are long (>50 lines) please provide them in a Gist or collapsed using HTML details tags. Take care to redact any sensitive info.

  8. Paste in the outputs of eksctl info where relevant, as well as anything else you have running which you think may be relevant.

  9. Detail any workarounds which you tried, it may help others who experience the same problem.

  10. If you already have a fix in mind, note that on the report and go ahead and open a PR whenever you are ready. A core team-member will assign the issue to you.

Feature request guide

We hope to respond to and prioritize new feature requests within 7 working days. Please wait for up to 14 before nudging us.

A feature request is the start of a discussion, so don't be put off if it is not accepted. Features which either do not contribute to or directly work against the project goals will likely be rejected, as will highly specialised use-cases.

Once you have opened the ticket, feel free to post it in the community slack channel to get more opinions on it.

Below are the steps we encourage people to take when creating a new feature request:

  1. Search existing issues. If something similar already exists, and is still open, please contribute to the discussion there.

  2. Explain clearly why you want this feature.

  3. Describe the behaviour you'd like to see. As well as an explanation, please provide some example commands/config/output. Please ensure everything is formatted nicely with code blocks. If you have strong ideas, be as detailed as you like.

  4. Explain how this feature would work towards the project's vision, or how it would benefit the community.

  5. Note the deliverable of this issue: should the outcome be a simple PR to implement the feature? Or does it need a design proposal?

  6. If the feature is small (maybe it is more of an improvement) and you already have a solution in mind, explain what you plan to do on the issue and open a PR! A core team member will assign the task to you.

Help request guide

While you can ask for general help with eksctl usage in the slack channel, opening an issue creates a more searchable history for the community.

We hope to respond to requests for help within a couple of working days, but please wait for a week before nudging us.

Once you have created your issue, we recommend posting it in the slack channel to get more eyes on it faster.

Please following these steps when opening a new help issue:

  1. Search existing issues. If something similar already exists, and is still open, please contribute to the discussion there.

  2. Write a title with the format "How to x".

  3. Explain what you are trying to accomplish, what you have tried, and the behaviour you are seeing.

  4. Please include your config (removing any sensitive information) or exact the commands you're using. Please ensure everything is formatted nicely with code blocks.

  5. When providing verbose logs, please use either a Gist or HTML detail tags.

Submitting PRs

Choosing something to work on

If you are not here to report a bug, 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 issue 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 😄.

    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 priority/<x> are also up for grabs, but are likely to require a fair amount of context.

Developing eksctl

Sections:

WARNING: All commands in this section have only been tested on Linux/Unix systems. There is no guarantee that they will work on Windows.

Getting started

Before you begin writing code, you may want to have a play with eksctl to get familiar with the tool. Check out the README for basic installation and usage, then head to the main docs for more information.

Setting up your Go environment

This project is written in Go. To be able to contribute you will need:

  1. A working Go installation of Go >= 1.12. You can check the official installation guide.

  2. Make sure that $(go env GOPATH)/bin is in your shell's PATH. You can do so by running export PATH="$(go env GOPATH)/bin:$PATH"

  3. (Optional) User documentation is built and generated with mkdocs. Please make sure you have python3 and pip installed on your local system.

Forking the repo

Make a fork of this repository and clone it by running:

git clone git@github.com:<yourusername>/eksctl.git

It is not recommended to clone under your GOPATH (if you define one), otherwise, you will need to set GO111MODULE=on explicitly.

You may also want to add the original repo to your remotes to keep up to date with changes.

Building eksctl

NOTE: If you are working on Windows, you cannot use make at the moment, as the Makefile is currently not portable. However, if you have Git and Go installed, you can still build a binary and run unit tests.

go build .\cmd\eksctl
go test .\pkg\...

Once in your cloned repo, you can install the dependencies and build the binary. The binary will be created in the root of your repo ./eksctl.

make install-build-deps
make build

To build and serve the user docs, execute the following:

# Requires python3 and pip3 installed in your local system
make install-site-deps
make build-pages
make serve-pages

Running the unit tests

To run the tests simply run the following after install-build-deps:

make test

If you prefer to use Docker, the same way it is used in CI, you can use the following command:

make -f Makefile.docker test

NOTE: It is not the most convenient way of working on the project, as binaries are built inside the container and cannot be tested manually, also majority of end-users consume binaries and not Docker images. It is recommended to use make build etc, unless there is an issue in CI that need troubleshooting.

Running the integration tests

NOTE: Some parts of the integration tests are not configurable and therefore cannot be run by folks outside the core team. If you are NOT contributing to the gitops functionality, you can run a subset of the tests which cover your change, see below.

NOTE: Integration tests a lot of infrastructure and are therefore quite expensive (in both sense of the word) to run. It is therefore not essential for community members to run them as the core team does this as part of the release process.

The integration tests are long and unfortunately there are some flakes (help is very welcome!).

There are several ways to run the tests. Requirements are:

  • An AWS account (it is recommended to use gsts to authenticate) which you are logged in to with a session token which won't expire for at least 2 hours.
  • An empty repository for testing gitops operations
  • A private key to that gitops repository

To run the full suite including cluster creations/teardowns:

TEST_V=1 make integration-test

To run the tests and save output to a file (recommended), run:

TEST_V=1 make integration-test 2>&1 | tee <some-name>.log

NOTE: The test suites are run in parallel, which means they write to stdout simultaneously. To parse logs for a specific test output, you can grep the logs based on the node number (eg. grep '\[9\]' int-tests.log > suite9.log)

To run the tests with a pre-created cluster for a faster turnaround:

TEST_CLUSTER=<name> make create-integration-test-dev-cluster
TEST_CLUSTER=<name> make integration-test-dev
TEST_CLUSTER=<name> make delete-integration-test-dev-cluster

To run a specific suite:

ginkgo -tags integration -v --progress integration/tests/<suite name>/... -- -test.v -ginkgo.v

Writing your solution

Once you have your environment set up and have completed a clean run of the unit tests you can get to work 🎉 .

  1. First create a topic branch from where you want to base your work (this is usually from main):

    git checkout -b <feature-name>

  2. Write your solution. Try to align with existing patterns and standards. However, there is significant tech debt, so any refactoring or changes which would improve things even a little would be very welcome. (See #2931 for our current efforts.)

  3. Try to commit in small chunks so that changes are well described and not lumped in with something unrelated. This will make debugging easier in the future. Make sure commit messages are in the proper format.

  4. Be sure to include at least unit tests to cover your changes. See the addon package for a good example of tests.

    NOTE: We are trying to move away from using mockery to generate our fakes. Where possible, please use counterfeiter instead.

  5. For extra special bonus points, if you see any tests missing from the area you are working on, please add them! It will be much appreciated ❤️ .

  6. Check the documentation and update it to cover your changes, either in the README or in the docs folder. If you have added a completely new feature please ensure that it is documented thoroughly and include an example.

  7. Before you open your PR, run all the unit tests and manually verify that your solution works.

  8. Note that editing certain things (eg. pkg/apis/eksctl.io/v1alpha5/types.go) will mean you need to ensure autogenerated files are updated. Not doing so will result in merge conflicts on your PR. Running make test will handle the generation. If you get into a state where you have forgotten to generate, and there is a conflict, you can resolve this by accepting HEAD in the conflict resolution, and then running make test again. You can then commit the generated files as part of your PR.

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 they do not respond, or more help is needed, you can then bring in one of the core maintainers.

  • 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. You can tag in one of the core team, or drop the PR link into slack and get help from the community.

  • We are happy to pair with contributors over a slack call to help them fine-tune their implementation. You can ping us directly, or head to the channel to see if anyone in the community is up for being a buddy 😃 .

PR submission guidelines

Push your changes to the branch on your fork and submit a pull request to the original repository against the main branch. Where possible, please squash your commits to ensure a tidy and descriptive history.

git push <remote-name> <feature-name>

If your PR is still a work in progress, please open a Draft PR.

Our GitHub Actions integration will run the automated tests and give you feedback in the review section. We will review your changes and give you feedback as soon as possible. We also encourage people to post links to their PRs in slack to get more eyes on the work.

We recommend that you regularly rebase from main of the original repo to keep your branch up to date.

Please ensure that Allow edits and access to secrets by maintainers is checked. While the maintainers will of course wait for you to edit your own work, if you are unresponsive for over a week, they may add corrections or even complete the work for you, especially if what you are contributing is very cool 🤘 .

PRs which adhere to our guidelines are more likely to be accepted (when opening the PR, please use the checklist in the template):

  1. The description is thorough. When writing your description, please be as detailed as possible: don't make people guess what you did or simply link back to the issue (the issue explains the problem you are trying to solve, not how you solved it.) Guide your reviewers through your solution by highlighting key changes and implementation choices. Try and pre-empt any obvious questions they may have. Providing snippets (or screenshots) of output is very helpful to demonstrate new behaviour or UX changes. (Snippets are more searchable than screenshots, but we wont be mad at a sneak peek at your terminal envs 👀 .)

  2. The change has been manually tested. If you are supplying output above then that can be your manual test, with proof 👏 .

  3. The PR has a snappy title. Your PR title will end up in the release notes, so make it a good one. Using the same rule as for the title of a commit message is generally a good idea. Try to use the imperative and centre it around the behaviour or the user value it delivers, rather than any implementation detail.

    eg: "changed SomeFunc in file.go to also handle clusters in new region X" is not useful for folks stopping by to quickly see what new stuff they can do with eksctl, save that for commit messages or the PR description. The title "Add support for region X" conveys the intent clearly.

  4. There are new tests for new code.

  5. There are new tests for old code! This will earn you the title of "Best Loved and Respected Contributor" 💥 😎 .

  6. There are well-written commit messages (see below) which will make future debugging fun.

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 two questions: what changed and why.

The subject line should feature the what and the body of the commit should describe the why.

Added AWS Profile Support

Changes to ensure that AWS profiles are supported. This involved making
sure that the AWS config file is loaded (SharedConfigEnabled) and
also making sure we have a TokenProvider set.

Added an explicit --profile flag that can be used to explicitly specify
which AWS profile you would like to use. This will override any profile
that you have specified via AWS_PROFILE.

If endpoints are being overridden then the credentials from the initial
session creation are shared with any subsequent session creation to
ensure that the tokens are shared (otherwise you may get multiple MFA
prompts).

Issue #57

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>
<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 80 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

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

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

These priority categories have been inspired by the Kubernetes contributing guide.

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.

Proposals

For chunky features which require Serious Thought™, the first step is the submission of a design proposal to the docs folder through the standard PR process.

Process

A template can be found in docs/proposal-000-template.md. Simply create a copy of the file (replacing the number with the next in the sequence, and 'template' with your feature name), and fill in the required fields. When ready, open a PR.

For the initial PR, we can try to avoid getting hung up on specific details and instead aim to get the motivation and the goals/non-goals sections of the proposal clarified and merged quickly. The best way to do this is to just start with the high-level sections and fill out details incrementally in subsequent PRs.

Initial bare-bones merging does not mean that the proposal is approved, the Status section will convey whether the proposal has been accepted and work has begun. Any proposals not marked as 'approved' is a working document and subject to change.

When editing proposals, aim for tightly-scoped, single-topic PRs to keep discussions focused. If you disagree with what is already in a document, open a new PR with suggested changes.

A proposal which has been accepted should become a living document. Even the best-laid plans rarely work out, so as things are learned during implementation the doc should be updated to accurately reflect the state of the world.

Sections

Each proposal/design doc should cover the following at a minimum:

  • The author(s). So that people know where to direct questions at any point in time.

  • Status. Proposals serve as documentation on the design of our codebase. It is useful to indicate whether what is documented reflects the state of the project.

  • Summary A TLDR of everything that is discussed in the doc.This should be written in a way that anyone can come by and quickly understand what the proposal is for.

  • Motivation for why we should do this, how it fits into the project's goals and how it will help users in the long term. What is the problem this proposal aims to solve? (Includes clear-cut Goals and Non-Goals, and all possible Context.)

  • Proposal of the solution to the above problem. This can be high-level, detail comes later. (This includes User Stories as well as Risks and Mitigations.)

  • Design details. How the proposal should be implemented. (Includes Test Plans, and Graduation Criteria.)

  • Alternatives. List the pros and cons of each solution considered, illustrating why the final one was chosen.

  • Known unknowns or open questions. The author should list any questions for things they are unsure about or to direct reviewers to particular areas where their expertise is needed.

Writing tips

  1. Write simply and keep your language accessible. The easier it is to understand, the more input you will get from a wider range of sources. Bear in mind that your target audience is anyone who comes into contact with eksctl: maintainers, contributors and end users.

  2. Refer to the Kubernetes documentation style guide.

  3. Don't assume too much knowledge. Make sure terms have explanations or links for the same reason as the last point.

  4. Use lots of yaml and diagrams (colour-coded, if possible 😉).

🚀 🎉 Thanks for reading! 🎉 🚀