okf-wiki/gates/calibration-folder/kilde/kettlewick-contributor-guide-and-release-process.docx.md
Kjell Tore Guttormsen 0fd86a23a3
okf-wiki 1.1.1
First public release, published as one snapshot. What changed between
versions is in CHANGELOG.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:03:20 +01:00

9.5 KiB

Kettlewick Contributor Guide and Release Process

Kettlewick Contributor Guide and Release Process

Version 4.2, effective 1 April 2026. Approved by the maintainers on 24 March 2026. This version replaces version 4.1 of 6 January 2026.

1. About this guide

This guide applies to everyone who contributes code, documentation, translations or reviews to the Kettlewick project. Maintainers must follow it in full. Contributors without commit access need to read sections 2 to 5 before opening their first pull request. Where this guide and an older wiki page disagree, this guide applies.

Changes in recent versions:

Version 4.1 (6 January 2026): changes to the index and store modules need two approvals; the feature freeze is 14 days instead of 7; the string freeze is 10 days before release.

Version 4.2 (1 April 2026): new section 8 on the steering council, after the governance proposal was approved on 14 March 2026; Felix Ondrasek added as standing substitute on the conduct committee.

2. Before you start

Every commit must carry a Signed-off-by line confirming that you have the right to submit the work under the project licence. Pull requests with unsigned commits are not merged.

Open an issue before you start on a large change. A change that touches more than 400 lines outside the tests, or that adds a new command, must have an issue with the label accepted before the pull request is opened.

Issues labelled good-first-issue are reserved for first-time contributors for 14 days after they are labelled.

Do not report security problems in public issues. Use the private security address described in section 6.

The Seedling mentoring programme pairs a new contributor with one maintainer for 12 weeks. Applicants must be at least 16 years old. Each cohort takes at most 6 mentees, and a maintainer may mentor only one mentee at a time. Applications close 4 weeks before a cohort starts.

Cohort

Application deadline

Start

End

Spring 2026

2 February 2026

2 March 2026

24 May 2026

Autumn 2026

3 August 2026

31 August 2026

22 November 2026

Commit access is offered to contributors who have had at least 10 pull requests merged over a period of at least 6 months and who are nominated by 2 maintainers. The nomination is accepted unless a maintainer objects within 7 days.

3. Pull requests and review

The number of approvals a pull request needs depends on what it changes. If a pull request touches more than one area, the strictest rule applies.

Area

Approvals needed

Who may approve

Notes

Core modules (index and store)

2

Maintainers

Since 1 January 2026; before that 1 approval

Command-line interface and other code

1

Maintainers

Plugins

1

Maintainers or plugin reviewers

Documentation only

1

Any maintainer

Must stay open for at least 48 hours before merging

Translations

1

The translation coordinator for that language, or any maintainer

Version bump before a release

1

Any maintainer other than the release manager

Exception to the self-merge rule below

A maintainer must not merge their own pull request. The only exception is the release manager, who may merge the version bump pull request after one approval from another maintainer.

Every pull request must pass the tests on Linux and macOS before it is merged.

Pull requests are merged by squash merge only.

Reviewers aim to give a first review within 5 days. If you have had no review after 5 days, you may ask in the review channel.

A pull request with no activity from its author for 60 days is closed with the label stale. The author may reopen it at any time.

4. Tests and benchmarks

Every bug fix must include a test that fails without the fix.

The coverage gate fails a pull request if total line coverage drops by more than 0.5 percentage points or falls below 82%.

Windows is tested only in the nightly run at 03:00 UTC. If the nightly Windows run fails because of your merged pull request, you are expected to help fix it within 7 days; otherwise the pull request may be reverted.

A flaky test may be moved to quarantine for at most 21 days, after which it must be fixed or deleted. No more than 10 tests may be in quarantine at the same time.

Do not add tests that need network access; they are skipped in the nightly run and do not count towards coverage.

Benchmarks run every Sunday at 02:00 UTC and on every release candidate, using a small corpus of 10,000 notes and a large corpus of 100,000 notes. You can ask for a benchmark run on your pull request by commenting /bench. Each pull request may have at most 3 requested runs, because the benchmark machine is shared by the whole project.

A pull request that makes median search latency or index build time more than 5% slower, or raises peak memory by more than 10%, on either corpus, is labelled perf-regression. It may be merged only with the approval of the performance lead, Mateus Kowalczyk, even if it already has the approvals required in section 3.

5. Issue triage

Triage is done by a weekly rota. The maintainer on duty covers Monday 00:00 UTC to Sunday 23:59 UTC. Every maintainer takes at least one week per quarter, and swaps must be recorded in the rota file before the week starts.

Every new issue should get a first response within 72 hours and a label within 7 days.

An issue labelled needs-info is closed if the reporter has not replied within 30 days. It can be reopened when the information arrives.

Duplicates are closed with a link to the older issue, even if the newer issue has more detail; the detail is copied across.

Feature requests are labelled feature and are not given a milestone until a maintainer agrees to review the work.

The person on duty must not close an issue they reported themselves.

6. Release process

Minor releases follow a fixed 13-week cadence and are published on a Tuesday. The planned dates for 2026 are 17 February (2.7.0), 19 May (2.8.0), 18 August (2.9.0) and 17 November (3.0.0). A late release does not move the next planned date. Each minor release has a release manager, who must have been a maintainer for at least 6 months. No one may manage two minor releases in a row. The release manager for 2.8.0 is Felix Ondrasek.

Step

When

Who

What it means

Feature freeze

14 days before release (a Tuesday)

Release manager

Only bug fixes and documentation may be merged into the release branch

String freeze

10 days before release (a Saturday)

Release manager and translation coordinators

No changes to user-visible text

First release candidate

7 days before release (a Tuesday)

Release manager

Published for testing; benchmarks run automatically

Final release

The planned Tuesday

Release manager

Only if no bug labelled blocker is open

Patch release

Normally 2 weeks after the minor release

Release manager of that minor release

Bug fixes only; no release candidate

A second release candidate is required if any change other than a documentation change is merged after the first release candidate.

The feature freeze was 7 days until the end of 2025. It was extended to 14 days from release 2.7.0 because two of the four minor releases in 2025 needed a second release candidate.

Releases are signed with the project key. The current key was created on 11 September 2025, has a lifetime of 3 years and expires on 11 September 2028. A reminder issue is opened automatically 90 days before expiry.

Security problems are reported to the private security address. The security team acknowledges a report within 3 working days. A fix is released and the advisory published within 30 days of the report, unless the reporter agrees to a longer embargo, which may never exceed 90 days. Security releases may be published on any day of the week and do not need a release candidate. Reporters are credited by name only if they agree.

7. Code of conduct reports

The code of conduct applies in all project spaces: the repository, the issue tracker, the chat channels and the annual meeting. Reports go to the conduct committee: Ruth Abernethy (chair), Dagny Oyelaran and Hollis Fenwick. Felix Ondrasek is the standing substitute.

The committee acknowledges a report within 48 hours and decides within 14 days.

A committee member who is involved in a report must step aside, and the standing substitute takes their place.

Possible outcomes are no action, a written warning, a temporary ban of up to 90 days from all project spaces, or a permanent ban.

A permanent ban needs a unanimous decision of the committee. From 1 July 2026 the person banned may ask the steering council to review it.

The reporter is told the outcome but not necessarily the details. Reports must not be discussed in public channels.

8. Governance from 1 July 2026

On 14 March 2026 the maintainers approved the proposal to replace the lead maintainer with an elected steering council. Eight maintainers voted for, none voted against and one abstained; at least 6 of 9 votes were needed. Until 30 June 2026 the lead maintainer, Imogen Varga, keeps the final say when maintainers cannot agree.

The steering council has 5 seats. In the first election 3 seats are for 2 years and 2 seats for 1 year; after that all terms are 2 years.

Candidates must have been maintainers for at least 12 months when nominations close.

Anyone with at least 5 merged pull requests in the 12 months before voting opens may vote.

No more than 2 council members may work for the same organisation.

The council decides by simple majority with a quorum of 4 members. Changes to the licence, the code of conduct or this section need 4 votes.

Nominations run from 1 to 21 April 2026 and voting from 1 to 14 May 2026. The council takes office on 1 July 2026.