Skip to content

Chef Software Inc. Contributor Guide

This document is a guide on how to contribute to and maintain Chef Software Inc. projects. Feel free to browse the open issues and file new ones, all feedback welcome!

Contributing to any of Chef's projects should be easy. If you find a rough edge, let us know! Better yet, join the community and help us fix it.

Welcome

Welcome to the Chef Software Inc. OSS Community!

Before You Get Started

Code of Conduct

Please make sure to read and observe our Code of Conduct).

Community Expectations and Roles

All Chef Software, Inc. OSS projects are operated as community projects. Consequently, it is wholly dependent on its community to provide a productive, friendly, and collaborative environment for all contributors.

Please be aware that due to the large number of issues, repos, and projects our teams administer, we do not offer technical support in GitHub issues or on Slack.

Your First Contribution

We're glad you're interested in contributing to a Chef project! We're here to do everything we can to make your first contribution experience a great one.

We hope this guide will help you to choose where to contribute, and show you the ropes of crafting your first contribution. If you have questions about the development process, or are feeling stuck with your first contribution, feel free to jump into specific project's public development Slack channel, or join a project-specific mailing list. The specific channels and mailing list URLs can be found in the CONTRIBUTING.md file found in each project repository.

Find Something To Work On

Help is always welcome! For example, documentation -- like the text you are reading now -- can always use improvement. There's always a need for more test coverage. There are surely un-prioritized features, which could use your work. Commenting on an issue that a bug or error is reproducible and including the environment and steps to reproduce will help with issue triage. Blog posts and example projects don't hack themselves! You get the idea - if you ever see something you think should be fixed, you should own it.

Find a Good First Issue

Chef Software maintains over 500 software repositories in multiple GitHub organizations such as chef, inspec, and habitat-sh. Each repository has beginner-friendly issues that have been labeled to help new contributors.

Chef uses labels to tag issues we believe are ideal for first time contributors as well as those ideal for outside contributors. See Help Wanted documentation for more information on how those tags are used and where you can see complete lists of tagged issues.

Contributing Without Coding

Not ready to contribute code, but still interested in helping? There are many non-coding ways to contribute to the community.

Documentation

Documentation is critical to the success of any project and can always use expansion and improvement. Many Chef projects include documentation directly in their repository, and we also maintain the code for docs.chef.io in our chef-web-docs repository. Documentation contributions are an excellent exposure to the code submission/review process without the added complication of technical depth. Please see Contributing below for the workflow.

File or Triage Issues

Both filing issues and triaging existing issues are incredibly helpful to maintain high quality software. Finding new issues in projects and filing detailed issues help the maintainers to provide the best possible experience to users. Be sure to adhere to the prompted submission guidelines when opening an issue to give the maintainers all the information necessary to resolve your issue.

Even more useful than filing new issues is confirming existing issues. Providing reproduction cases or more detailed information to existing issues smooths the triage process and ensures issues can be more easily resolved by developers.

Learn About the Project's Team

Once you've found your first project and an issue, it's important to learn about the team responsible for that project.

Team Structure

We organize our community into teams in order to improve our workflow and more easily manage what amounts to multiple very large community projects. The developers within each team have autonomy and ownership over that team's project(s) and frequently a team will be working on more than one project at once.

All projects at Chef are operated as open, community efforts supported with internal development teams. Anyone is welcome to jump into a project or engage with a specific team and begin filing/updating issues, writing/updating documentation, fixing issues, participating in design discussions, or reviewing code. Each team should have a public Slack channel for development discussions though any team is welcome to share a public development channel with any other team.

Find the Project's Team

Finding the appropriate team for your contribution and asking your questions in the correct place can give your contribution higher visibility and a faster community response. We do our best to have a swift response time on any of our projects, but engaging a team directly on a contribution is a great way to get connected and have a more direct interaction around your contribution.

The readme file in each project repository will contain information on the team responsible for the code. Some teams also have their own CONTRIBUTING.md files, which may contain extra information or guidelines in addition to these general ones. These are located in the team-specific community directories in this repository and will be linked from any repository that team owns.

Claiming Your Issue

You've found the issue you want to work on and now you want to make sure that no one else beats you too it. Often, new contributors ask to be assigned an issue they are willing to take on. Unfortunately, due to GitHub limitations we can only assign issues to org members or repo collaborators. Instead, leave a comment that you're going to start work on the issue and others will make sure to give you space.

Contributing

All Chef Software Inc. projects are open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully, these rules make things go more smoothly. If you find that this is not the case, please open an Issue on this repository.

As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a pull request. Don't assume that a contribution is 'too small' or 'not important' - all inputs are welcome, and will be discussed in a friendly and inclusive manner.

Check out our Collaborative Development Principles on how to create great code as a big group.

Beginner focused information can be found below in Open a Pull Request and Code Review.

For quick reference on contributor resources, we have a handy contributor cheatsheet.

Signing the DCO

Chef requires that all commits to projects be signed for the DCO. See Developer Certificate of Origin for more information on why we use the DCO and how to sign a commit for the DCO.

Communication

It is best to contact a project's team for issues related to the projects operated by that team. Your team will be able to help you much more quickly than a general question would.

For information on finding the team responsible for a project see Find the Project's Team.

For general questions and troubleshooting, see the standard lines of communication.

Open a Pull Request

Pull requests are often called simply "PR"s. Our community generally follows the standard GitHub pull request process, but there is a layer of additional project specific (and sometimes team specific) differences:

Common new contributor PR conflicts are:

  • not having correctly signed the DCO on the commits of your first PR (see Signing the DCO section)
  • finding the right team or reviewer(s) for the PR (see Code Review section) and following any team or repository specific contributing guidelines (see Team Structure section)
  • dealing with test cases which fail on your PR, unrelated to the changes you introduce

Code Review

It is critical that all code changes to projects be reviewed to promote high quality work, foster development norms, and keep contributors and community members engaged and apprised of changes.

Please read the Code Review section of the Collaborative Development Principles guide for further information on helping project members to better review your changes.

Testing

Testing is critical to preventing regressions and for the general maintenance of high quality software over time. All Chef projects require testing and that testing is the responsibility of all contributors.

Refer to the Testing section of the Collaborative Development Principles guide for further information.

Security

Issues Management or Triage

Helping to manage or triage open issues can be a great contribution and a great opportunity to learn about the various areas of the project. Triaging is the word we use to describe the process of adding multiple types of descriptive labels to GitHub issues, in order to speed up routing issues to the right folks.

Community

If you haven't noticed by now, we have a large, lively, and friendly open-source community. We depend on new people becoming project members and regular code contributors, so we would like you to join us!

The Project Membership Document covers membership processes and roles.

Community Communication

Events

Chef Inc. participates in an extremely diverse and distributed list of events every year across Asia, Europe and North America. Information about these and other community events is available on the Chef events pages.

More Ways to Contribute

Code is certainly not the only way to contribute, check out this list of ways to contribute