Kotlin KEEP: where the language's design decisions are actually written down

What a KEEP is and is not

The repository describes itself as containing proposals for the Kotlin programming language, including draft design notes and discussions for in-progress proposals as well as the design documentation for changes that were already implemented. The proposals themselves are called KEEPs, an informal name for the numbered documents.

The scope is both the language and the standard library, which is broader than a design-notes archive for a compiler would be. A KEEP can therefore cover a language feature, a type system change, a coroutine or serialization design, or an API addition, and the document stays in the repository after the implementation lands.

One line in the README redirects readers who expect to find code here. The implementation of a design enhancement usually lives in the Kotlin source repository at JetBrains/kotlin, not in this one. What this repository holds is the reasoning: the problem, the considered alternatives, the chosen syntax, and the migration notes. For a reader trying to understand why a construct exists, that is the more valuable artefact anyway, since the code shows what was built and the KEEP shows what was rejected.

The repository is Markdown, licensed Apache 2.0, and sits at 3,770 stars with 385 forks and 12 open issues. There are no releases, which is correct for a document repository rather than a sign of neglect.

The three-stage lifecycle and who does what

The README lays out the process in three numbered stages, and the division of labour is what makes it worth reading.

Stage one is publication. Every new proposal gets a KEEP number, assigned as the previous proposal number plus one, and the Markdown file is prefixed with that number and merged into the `main` branch. Stage two is public review: immediately after publication a GitHub Discussion is opened, and the community is invited to read and respond there. Stage three is the decision, where the proposal is accepted, rejected, or sent back for further refinement.

The README also points you at YouTrack. For a proposal you care about, it says to follow the YouTrack issue, which is usually mentioned in the KEEP document header. So there are two places a feature's story lives, split between a long-form document and a tracker issue, and the header link is how you connect them.

The status has to be recorded in the document header, and the README calls that out as a requirement rather than a convention. This is the part that determines how useful the archive is years later. The vocabulary includes `Public discussion`, `In progress`, `Experimental in 2.0.0`, `Stable`, `Stable in 2.1.0`, `Declined`, `Unknown`, and `Superseded by KEEP-xxxx`. Two of those are explicitly marked discouraged in the README: `Stable` as an old status and `Unknown` as one used for old proposals. The version-pinned forms are the useful ones, because they tell you not just that a feature shipped but in which release.

Two things this vocabulary has not kept up with. The list still names 2.0.0 and 2.1.0 as its version examples, which means for anything landing in a later release the status value has no established template, and the whole list reads as the vocabulary as of an earlier Kotlin version rather than as a maintained enum. If you are checking whether a recent feature is stable, the release notes are the more reliable source.

Design notes, and the difference from a proposal

Not everything reaches proposal stage, and the repository has a separate category for the rest. The README calls these design notes and stores them in a `notes` directory, distinct from the `proposals` directory that holds the KEEPs.

The distinction is about completeness rather than importance. A design note represents a direction worth discussing that is not yet specific enough to be a proposal. The README says such ideas still need to be discussed with the community to gather use cases, their potential syntax, and the impact on existing Kotlin code. That is an honest admission that the design is unresolved, and reading a note tells you the shape of an idea without telling you what the API will be.

This split is more useful than it sounds. Language evolution produces far more ideas than it accepts, and a repository that kept only accepted proposals would give a false impression of how the language thinks. With notes kept separately, you can see the directions under discussion, which is the earlier signal of where the language is heading.

The tree also contains a `resources` directory whose contents the README does not describe, so its role is undocumented from here. If you are looking for templates or shared assets for writing a proposal, that directory is the place to look, along with the contribution guide.

How to contribute when you cannot send a proposal

The contribution rules are the most unusual thing about this repository, and they are easy to skim past.

The README states plainly: pull requests that submit new KEEP proposals are not expected. Instead, the route is a YouTrack issue in the Language Design subsystem. The reasoning given is that many popular enhancements and language design problems are already filed there, and that the most valuable contribution is a real-life use case. So the asked-for contribution is to vote for issues you encounter in your own work and to comment with a description of your specific use case.

That is a deliberate constraint on a process that otherwise invites participation. A repository whose subject is community language design does not accept community-authored proposals, which keeps the burden on the language team and avoids a queue of unvetted documents. It also means the only way to move a feature forward is to make the case in the tracker.

Two narrower contribution paths do exist. For an in-progress KEEP, discussion belongs in the corresponding GitHub Discussion thread rather than in the pull request. And for text corrections to proposals that are already merged, the README asks for a separate pull request, which is a reasonable convention for keeping editorial changes out of feature discussions.

Mechanically, the repository enforces the numbering. The tree contains `check-uniq-keep-ids.kts`, and the README badge points at a workflow of that name, so uniqueness of KEEP identifiers is checked in continuous integration. That catches collisions but not the convention itself: the rule that a new number is the previous number plus one is still maintained by hand.

Following along without watching a repository

The README gives two ways to keep up, and both are chosen so you do not have to watch the repository.

The first is a Slack channel, `#language-proposals` in the public Kotlin Slack, with an invite link provided. The second is an RSS feed, pointed at the GitHub Discussions category for KEEP discussions, sorted by date created. Both exist because proposals are announced rather than merged silently, and a discussion is opened as soon as a proposal is published rather than after the decision.

That timing is the thing to internalise if you want to have a say. The window for influencing a proposal is the public review stage, which starts the moment the document appears, not the point at which implementation begins. Reading the feed is how you find out a proposal exists in time to comment on it; finding out from the release notes means the decision is already made.

The homepage for the repository is the language features and proposals page on kotlinlang.org, which is the rendered view for readers who do not want to browse raw Markdown. For a developer deciding whether to adopt a Kotlin feature, the useful order is to read the release notes for what shipped, then open the linked KEEP to find out what else was considered and why the alternatives lost. For a developer trying to change the language, the order reverses: open YouTrack, find or file the issue, and bring a use case rather than a syntax proposal.

Editorial conclusion

KEEP is the closest thing Kotlin has to a public record of why the language looks the way it does, and its practical value to a developer is narrow and specific: it is where you find the design rationale for a feature you already use. Knowing that a status line reading `Stable in 2.1.0` came from an accepted proposal with a linked YouTrack issue tells you both what shipped and what was rejected along the way. Two structural limits are worth internalising. The status vocabulary is version-pinned and last mentions 2.0.0 and 2.1.0, so for anything recent the proposal header may lag the release notes. And the repository refuses pull requests that propose new features by design, routing that through YouTrack instead, so do not plan to contribute a KEEP as a pull request. To follow along, the README names two channels: the Kotlin Slack language-proposals channel and the RSS feed for the keep-discussions category on GitHub Discussions.

Frequently asked questions

Official sources

1. Issues
2. Kotlin/KEEP on GitHub
3. License: Apache-2.0
4. Project website
5. README