hip-0001.md

hip	title	authors	created	type	status
0001	Writing a HIP	Matthew Fisher <matt.fisher@microsoft.com>	2020-08-13	process	accepted

Abstract

A HIP is a Helm Improvement Proposal. It is a design document providing information to the Helm community, or describing a new feature for a Helm project or its processes or environment. The proposal should provide a concise technical specification of the feature and a rationale for the feature.

We intend HIPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into the project. The proposal author is responsible for building consensus within the community and documenting dissenting opinions.

The system is heavily influenced by Python's Enhancement Proposal (PEP) system, hence the name. Given that Helm is a much (MUCH) smaller project than Python, there are a few changes in the HIP workflow to make it a looser format for proposals, most notably the lack of proposal "editors", a BDFL, and a much smaller review & resolution cycle.

Because the proposals are maintained as markdown files in a versioned repository, their revision history is the historical record of the proposal.

Audience

The typical primary audience for proposals are the project maintainers for each Helm project, as well as the Helm project's org maintainers.

However, other parts of the Helm community may also choose to use the process (particularly for informational proposals) to document expected conventions and to manage complex design coordination problems that require collaboration across multiple projects.

HIP types

There are three kinds of proposals:

1. A feature proposal describes a new feature or implementation for the Helm project. It may also describe an interoperability standard that will be supported by the Helm project.
2. An informational proposal describes a Helm design issue, or provides general guidelines or information to the Helm community, but does not propose a new feature. Informational proposals do not necessarily represent a Helm community consensus or recommendation, so users and implementers are free to ignore informational proposals or follow their advice.
3. A process proposal describes a process surrounding the Helm project, or proposes a change to (or an event in) a process. Process proposals are like feature proposals, but apply to areas other than the Helm project itself. They may propose an implementation, but not to Helm's codebase; they often require community consensus. Unlike informational proposals, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Helm development.

HIP workflow

Start with an idea

The proposal process begins with a new idea for the Helm project. It is highly recommended that a single proposal contain a single key proposal or new idea. Small enhancements or patches often don't need a proposal and can be injected into a project's development workflow with a patch submission to the project's issue tracker. The more focused the proposal, the more successful it tends to be. As per Helm's governance, the project maintainers reserve the right to reject proposals if they appear too unfocused, too broad, or incomplete. If in doubt, split your proposal into several well-focused ones, or explain your proposal more clearly.

Each proposal must have a champion -- someone who writes the proposal using the style and format described below, shepherds the discussions in the appropriate communication channels, and attempts to build community consensus around the idea. The proposal champion (a.k.a. author) should first attempt to ascertain whether the idea is proposal-able. Posting to the cncf-helm mailing list is the best way to go about this.

Vetting an idea publicly before going as far as writing a proposal is meant to save the potential author time. Many ideas have been brought forward for changing Helm that have been rejected for various reasons. Asking the Helm community first if an idea is original helps prevent wasting time on something that is guaranteed to be rejected based on prior discussions (searching the internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most Helm users in most areas where Helm is used.

Once the champion has asked the Helm community as to whether an idea has any chance of acceptance, a summary of the proposal should be presented to cncf-helm. This gives the author a chance to flesh out the proposal as a high quality, well-formatted proposal, and to address initial concerns about the proposal.

Submitting a HIP

Following a discussion on cncf-helm, the proposal should be submitted as a proposal via a GitHub pull request. The proposal must be written in proposal style as described below, else it will fail review immediately (although minor errors may be corrected by the maintainers).

The standard HIP workflow is:

• You, as the proposal author, fork the helm/community repository and create a new proposal
• Proposals are written in Markdown
• Push your proposal to your GitHub fork and submit a pull request.

Once the review process is complete, the reviewers will approve the proposal by commenting on the proposal with a "Looks good to me" ("LGTM" for short) and merge the proposal. (note that this is not the same as accepting your proposal!)

The reviewers will not unreasonably deny a proposal. Reasons for denying proposal status include duplication of effort, being technically unsound, not providing proper motivation, not addressing backwards compatibility, or not in keeping with Helm's design. The core maintainers can be consulted during the approval phase.

Once approved, proposal authors are responsible for collecting community feedback on a proposal before submitting a feature that satisfies the proposal for review. However, wherever possible, long open-ended discussions on public mailing lists should be avoided. Strategies to keep the discussions efficient include: setting up a separate meetings for the topic, having the proposal author accept private comments in the early design phases, setting up a wiki page, etc. proposal authors should use their discretion here.

What belongs in a successful HIP

Each HIP should include the following parts:

1. Preamble - YAML style headers containing metadata about the proposal, including the proposal number, a short descriptive title, the author names, its current status, etc.
2. Abstract - a short (~200 word) description of the technical issue being addressed.
3. Specification - The technical specification should describe the syntax and semantics of any new feature. If the proposal describes a standard, the specification should be detailed enough to describe how other community members may re-implement the standard in their product.
4. Motivation - The motivation is critical for proposals that want to change Helm in a significant way. It should clearly explain why existing features are inadequate to address the problem that the proposal solves, as well as who and what profiles/roles are impacted by this proposal. Proposal submissions without sufficient motivation may be rejected outright.
5. Rationale - The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other projects.
6. Backwards Compatibility - Helm projects follow Semantic Versioning. Therefore, all proposals that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The proposal must explain how the author proposes to deal with these incompatibilities. Proposal submissions without a sufficient backwards compatibility treatise may be rejected outright.
7. Reference Implementation - The reference implementation must be completed before any proposal is given status "final", but it need not be completed before the proposal is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.

The final implementation must include test code and documentation appropriate for the Helm project's reference or the community at large.

Preamble

Each proposal must begin with a YAML style header preamble. The headers must appear in the following order:

Headers marked with "*" are optional and are described below. All other headers are required.

---
hip: <HIP number>
title: "<HIP title>"
authors: [ "<list of authors' real names and optionally, email addresses>" ]
created: "2020-08-13"
type: "<feature | informational | process>"
status: "<draft | accepted | provisional | deferred | rejected | final | superseded>"
* helm-version: "<version number>"
* requires: [ <HIP numbers> ]
* replaces: <HIP number>
* superseded-by: <HIP number>
---

The authors header lists the names, and optionally the email addresses of all the authors/owners of the proposal. The format of the author header value must be

authors: [ "John Doe <john@example.com>", "Jane Doe <jane@example.com>" ]

If the email address is included, and

authors: [ "John Doe", "Jane Doe" ]

If the address is not given.

The created header records the date that the proposal was published to the Helm project on Github. The header should be in RFC 3339 format, e.g. 2020-08-13.

Proposals will typically have a helm-version header which indicates the version of Helm that the feature will be released with. Proposals without a helm-version header indicate interoperability standards that will initially be supported through external libraries and tools, and then supplemented by a later proposal to add support to the project's client library or Command Line Interface. Informational and process proposals do not need a helm-version header, and this header can be added after the implementation has been shipped and the proposal is marked as "final".

Proposals may have a requires header, indicating the proposal numbers that this proposal ends on.

The type header specifies the type of proposal: feature, informational, or process.

The status header specifies which state the proposal is in. A proposal always begins in "draft" status, and the other statuses are explained below.

Proposals with the superseded status may also have a superseded-by header indicating that a proposal has been rendered obsolete by a later document; the value is the number of the proposal that replaces the current document. The newer proposal must have a replaces header containing the number of the proposal that it rendered obsolete.

Auxiliary files

proposals may include auxiliary files such as diagrams. Such files must be named proposal-XXX-YY.ext, where "XXX" is the proposal number, "YY" is a serial number (starting at 01), and "ext" is replaced by the actual file extension (e.g. "png").

Sample template

If you intend to submit a HIP, it is highly recommended to use this template to ensure that your HIP submission won't be automatically rejected because of form.

How to use this template

To use this template you must first decide whether your HIP is going to be an informational, process, or feature HIP. Most HIPs are of type "feature" because they propose a new feature for the Helm project or client library.

Once you've decided which type of HIP yours is going to be, make a copy of this file and perform the following edits:

• Do NOT change the hip: 9999 header since you don't yet have a HIP number assigned... Yet. This is to prevent merge conflicts with other HIPs.
• Change the title header to the title of your HIP.
• Change the authors header to include your name(s), and optionally your email address(es). Be sure to follow the format carefully: your name must appear first, and it must not be contained in parentheses. Your email address may appear second (or it can be omitted) and if it appears, it must appear in angle brackets. It is okay to obfuscate your email address.
• Change the created header to the current date, following RFC 3339 format.
• For feature HIPs, change the type header to "feature".
• For informational HIPs, change the type header to "informational".
• For process HIPs, change the type header to "process".
• Do NOT change the status header from draft.
• For feature HIPs, if your feature depends on the acceptance of some other currently in-development HIP, add a requires header right after the status header. The value should be the HIP number of the HIP yours depends on. Don't add this header if your dependent feature is described in a "final" HIP.
• Add a replaces header if your HIP obsoletes an earlier HIP. The value of this header is the number of the HIP that your new HIP is replacing. Only add this header if the older HIP is in "final" form, i.e. is either accepted, final, or rejected. You aren't replacing an older open HIP if you're submitting a competing idea.
• Now write your abstract, rationale, and other content for your HIP, replacing all this gobbledygook with your own text.
• Update your references section.

---
hip: 9999
title: ""
authors: [ "" ]
created: "2020-08-13"
type: "feature"
status: "draft"
---

## Abstract

A short (~200 word) description of the technical issue being addressed.

## Motivation

Clearly explain why the existing design is inadequate to address the problem
that the HIP solves.

## Rationale

Describe why particular design decisions were made.

## Specification

Describe the syntax and semantics of any new feature.

## Backwards compatibility

Describe potential impact and severity on pre-existing code.

## Security implications

How could a malicious user take advantage of this new feature?

## How to teach this

How to teach users, new and experienced, how to apply the HIP to their work.

## Reference implementation

Link to any existing implementation and details about its state, e.g.
proof-of-concept.

## Rejected ideas

Why certain ideas that were brought while discussing this HIP were not
ultimately pursued.

## Open issues

Any points that are still being decided/discussed.

## References

A collection of URLs or materials used as references through the HIP.

Proposal review & resolution

Once the authors have completed a proposal, they may request a review for style and consistency from the project maintainers.

The final authority for proposal approval is the project maintainers responsible for the project the proposal is aimed at. However, whenever a new proposal is put forward, any project maintainer that believes they are suitably experienced to make the final decision on that proposal may offer to review the proposal, and they will have the authority to approve (or reject) that proposal. Individuals taking on this responsibility are free to seek additional guidance from other project maintainers at any time, and are also expected to take the advice and perspectives of other project maintainers into account.

Such self-nominations are accepted by default, but may be explicitly declined by the project or org maintainers. Possible reasons for the maintainers declining another maintainer's review include, but are not limited to, perceptions of a potential conflict of interest (e.g. working for the same organisation as the proposal submitter), or simply considering another potential maintainer to be more appropriate. If project maintainers (or other community members) have concerns regarding the suitability of a reviewer for any given proposal, they may ask the org maintainers to review the case.

To allow gathering of additional design and interface feedback before committing to long term stability for a feature or client library API, a HIP may also be marked as "provisional". This is short for "provisionally accepted", and indicates that the proposal has been accepted for inclusion in the reference implementation, but additional user feedback is needed before the full design can be considered "final". Unlike regular accepted proposals, provisionally accepted proposals may still be rejected even after the related changes have been included in a project's release.

Wherever possible, it is considered preferable to reduce the scope of a proposal to avoid the need to rely on the "provisional" status (e.g. by deferring some features to later proposals), as this status can lead to version compatibility challenges in the wider Helm ecosystem.

A proposal can also be assigned the status "deferred". The proposal author or a maintainer can assign the proposal this status when no progress is being made on the proposal. Once a proposal is deferred, a maintainer can re-assign it to draft status.

A proposal can also be "rejected". Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact.

Feature and Informational proposals require at least 2 approvals from project maintainers. Process proposals require at least 2 approvals from Helm org maintainers.

When a proposal is accepted or rejected, the proposal should be updated accordingly by updating the status field, and a link to any relevant information should be provided in the introduction.

What to do after a proposal has been approved

Once a proposal has been approved, the reference implementation must be completed. When the reference implementation is complete and incorporated into the project's source code repository, the status will be marked as "final".

Transferring proposal ownership

It occasionally becomes necessary to transfer ownership of proposals to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred proposal, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the proposal process, or has fallen off the face of the earth (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because the author doesn't agree with the direction of the proposal. One aim of the proposal process is to try to build consensus around a proposal, but if that's not possible, an author can always submit a competing proposal.

If you are interested in assuming ownership of a proposal, you can also do this via pull request. Fork the helm/community repository, make your ownership modification, and submit a pull request. You should also send a message asking to take over, addressed to both the original author and the org maintainers (@helm/org-maintainers). If the original author doesn't respond to email in a timely manner, the org maintainers will make a unilateral decision (it's not like these decisions can't be reversed).