Contribution Maintenance Policy

Contribution Policy

The Contribution Policy defines how we make decisions about what happens with
Habitat and associated software projects. It provides the process by which:

  • Patches are merged
  • Disputes are resolved

It is intended to be short, flexible, and clear.

This file is related to the MAINTAINERS

How the project is maintained

This file is the canonical source for how the Habitat project is maintained.


Project Lead

  • Resolves disputes
  • Provides vision and roadmap
  • Has universal veto power
  • There can be only one


  • Each component in the project may have one or or Owners
  • Provides guidance on future direction for their component
  • Resolves disputes within their component
  • Has localized veto power
  • An Owner must approve changes to the component they own
  • Plus all the responsibilities of a Maintainer


  • Each component may have multiple Maintainers
  • Handles contributions on GitHub - first response to a PR within 48 hours
  • Is available on Slack
  • Is available to answer mailing list questions within 48 hours
  • Weekends and local holidays in the Maintainer’s jurisdiction are not counted
    for timeliness requirements. Absences for reasonable causes such as vacations,
    illness, etc. are also acceptable; Maintainers should notice of absences via
    slack list whenever possible.
  • Committed to 100% tests passing for your component
  • Has full commit/merge access to the relevant repositories

Triage Process

Currently any member of the Core-Maintainers group on github can triage an issue in any of the habitat-sh organization repositories. A maintainer may assign any tags they wish at any time they please. Typically when a core maintainer triages an issue they will tag it with at least an “Area” tag and a “Category” tag (for a full list of tags and their definitions you can check out our wiki entry on the subject). Ideally we prefer the maintainer to also tag the issue with an “Effort” tag so as to maximize accessibility for external contributions. “Language” tags and “Status” tags are both fairly optional and exist again to lower the barrier to entry for new contributors. Since we’re using Github projects for a majority of our prioritized issues, community members and users should be able to track the status of prioritized issues on the project board. Basically, the process for applying these tags is at the discretion of the core maintainers. Maintainers are encouraged to make triage a regular part of their process and apply these tags to all issues as they have time.


A final note on our triage process is about milestones. Currently the Habitat project uses milestones as buckets for sorting our triaged issues. An important note on this process. Features and bugs can move between these milestones. As the project grows, changes, and we receive feedback, things will definitely be re-prioritized which means potentially having items shift between buckets. If you have bugs or features you really want to see in an upcoming release, we would love to have you contribute PRs for those things! You can find all of our “Help Wanted” issues for Habitat on the GitHub Issue Tracker!

  • Accepted Major
    The “Accepted Major” milestone should be pretty straightforward. Issues triaged into this category are features with breaking changes or with a very large scope. A change too drastic to include in a minor release.

  • Accepted Minor
    Our “Accepted Minor” milestone is the bucket for work that our Core Engineering team intends to implement or resolve. If an issue gets shoveled into this category, it means that it’s work we intend to take on ourselves (though, of course, we’re always happy to have PRs from the community for features or bugs in this bucket). Any issues that get added into the “Accepted Minor” milestone will be transferred to the Core Engineering backlog at a later date.

  • Help Wanted
    The final milestone is “Help Wanted” which covers issues or feature requests that we definitely want to implement, but might be at a lower priority than issues and bugs in the other two milestones. Issues in this category are likely to be great opportunities for community members to contribute to the codebase. The “Help Wanted” milestone is where we really want to encourage community development focused efforts.

Public Project Triage

Every Tuesday afternoon there is a public, open triage process focused on making sure that all new issues for the week that have not yet been placed into a milestone, get sifted, sorted, and labeled. The focus for this triage event (at least right now) is to ensure that new issues have been labeled correctly and with the most useful labels to anyone who may decide to work them whether those individuals are core maintainers or not. Those in leadership roles for the project are encouraged to attend and lend their expertise. We track the minutes of those calls in a thread on the forums.

Contributing Code

Feature Pipeline

A majority of the feature work the core team is doing currently is prioritized by the Habitat product owner. Those features will be given issues and labels like all other work in the codebase and added onto the core engineering project board. Many of the issues on this board are created by the core maintainers. But this board will also include features and bugs that have the Accepted Minor milestone.

The project and our community is currently an easily managed size so we do not currently have an overly complex RFC process. For features that might include breaking changes, or that are a bit more complex or touch important habitat subsystems we suggest contributors to open an issue that includes [RFC] in the title. Doing so will put the issue on the maintainers radar. When the issue is triaged it will be labeled with the C-RFC tag. RFCs will get reviewed once per week by the whole team, but maintainers are encouraged to add discussion to these issues outside of public triage as they have the time.

Lots of new features might require community input. So, we suggest that the contributor whom submits the issue make sure to post about it in community channels to drum up user input. Contributors should also feel comfortable using the @core-maintainers slack notifier to notify the maintainers that the RFC has been opened.

In the case of an RFC being opened the core maintainers may request separate issues to be created for various aspects of the feature (dependent wholly on the size of the incoming work) which will be linked back to the original RFC. In the case that the RFC is a manageable chunk of work for an individual the issue will get sorted to Accepted Minor or Accepted Major milestones, the core engineering project board and the RFC prefix will be removed.

How a patch gets merged

  • Open a Developer Certificate of Origin-signed (DCO-signed) Pull Request
  • Code reviewed by a Maintainer, Lieutenant, or Project Lead. Approval is
    indicated by :+1: on the pull request. Sometimes the :+1: will come in the form
    of a dank gif.
  • Merged after :+1: vote or r+ by at least one Maintainer for the component(s)
    affected by your patch. The merge is initiated by an r+ from an approved
  • Dank gifs are an integral part of PR approval.

Pull Request Review and Merge Automation

Habitat uses several bots to automate the review and merging of pull requests.
Messages to and from the bots are brokered via the account @thesentinels. First,
we use Facebook’s mention bot to
identify potential reviewers for a pull request based on the blame information
in the relevant diff. @thesentinels can also receive incoming commands from
reviewers to approve PRs. These commands are routed to a bot that will automatically
merge a PR when a reviewer with sufficient priviliges issues an @thesentinels approve.

Any Maintainer may vote :-1: on a patch, which increases the requirement for a
patch to be merged to an absolute majority of Maintainers for the affected
component(s), unless that Maintainer later changes their vote.

Patch and Issues Appeals Process

There may be cases where someone wishes to appeal a Maintainer decision. In this
event, the “chain of command” for the appeals process is as follows.

  • In the event that the actions of a Maintainer are to be appealed, the appeal
    should be directed to the Lieutenant for that component. As stated above, a
    Lieutenant retains veto power for the component(s) for which they are

  • In the event that the actions of a Lieutenant are to be appealed, the appeal
    should be directed to the Project Lead. As stated above, the Project Lead
    retains universal veto power over all components.

Although Lieutenants and the Project Lead retain veto powers over certain
components, use of this veto power is not guaranteed by the submission of an
appeal to that person. It is expected that the majority decisions of component
Maintainers and Lieutenants will be respected in all but the most exceptional

How to become a…


  • Have patches merged into the relevant component
  • Be willing to perform the duties of a Maintainer
  • Issue a pull request adding yourself to the MAINTAINERS file for your
  • Receive an absolute majority of existing Maintainers and Lieutenants for your
    component via :+1:s on the pull request
  • No veto from the component Owner
  • No veto from the current Project Lead


  • Issue a pull request to the CODEOWNERS file making yourself the Owner
  • Be willing to perform the duties of am Owner
  • Receive an absolute majority of existing Owners via :+1:s on the pull
  • No veto from the current Project Lead

Project Lead

  • Issue a pull request to the MAINTAINERS file making yourself the Project Lead
  • Be willing to perform the duties of the Project Lead
  • Receive an absolute majority of existing Owner via :+1:s on the pull
  • No veto from Chef Software, Inc., as held by their current Chief Executive

Removing a Maintainer, Owner or Project Lead

If a Maintainer, Owner, or Project Lead consistently fails to maintain
their responsibilities or becomes disruptive, they can be removed by:

  • Issue a pull request removing them from the MAINTAINERS/CODEOWNERS file
  • Receive an absolute majority of existing Lieutenants via :+1:s on the pull
  • No veto from the current Project Lead


  • Issue a pull request removing them from the MAINTAINERS file
  • The current Project Lead unilaterally decides to merge pull request

Active/Inactive Maintainer Rotation

We know that maintaining open source software might not be your daily gig. Which at times means that you’ll simply be too busy to triage issues, or comment on PRs. That being said we do have an expectation of activity for Owners and maintainers, but we want to include a safety net for folks that might need to bow out and return as time permits. As such the Habitat project has implemented a concept of Active and Inactive maintainers. If an Active maintainer goes a month without interacting with the project or other maintainers (PRs Comments/Code, Issue Triage/Comments, Slack Interaction, etc.) the maintainer will be be rotated from Active status to Inactive and will lose their project/repo permissions.

Should you return to Activity, you’ll simply want to Open a PR against the to rotate yourself back into the Active maintainer list (subject to all the same governance and process as being added initially). At this point an active maintainer can restore your permissions to the repository.

In the case of being an Owner and not simply a maintainer, your Ownership of a component will be revoked, and you’ll be added to the list of Inactive Maintainers. In order to restore your Ownership status you’ll need to Open a PR against both the CODEOWNERS and MAINTAINERS files (subject to all the same governance and process as being added initially) to return yourself to active status.


  • You have all of the previously identified rights and responsibilities of a maintainer. This includes your merge permissions, tagging permissions, systems access etc.
  • You are listed as an Active maintainer


  • You will be added to the Inactive maintainers list.
  • Your repo/system permissions and responsibilities are suspended.
  • If you are an owner, you will be removed from CODEOWNERS and added to the inactive maintainer list.

How to add a component

  • Issue a pull request to the CODEOWNERS file describing the component, and
    making yourself Lieutenant
  • Be willing to perform the duties of a Owner
  • Receive an absolute majority of existing Owner via :+1:s on the pull
  • No veto from the current Project Lead

How to change the rules by which the project is maintained

  • Issue a pull request to this file.
  • Receive an absolute majority of existing Owners from the Habitat
    repository MAINTAINERS file via :+1:s on the pull request
  • No veto from the current Project Lead

The MAINTAINERS file in Habitat

The current
file resides in the habitat repository
on GitHub.