Skip to content

Latest commit

 

History

History
115 lines (70 loc) · 5.74 KB

CONTRIBUTING.md

File metadata and controls

115 lines (70 loc) · 5.74 KB

Contributing to Sable

First off, thanks for taking the time to contribute! ❤️

All types of contributions are encouraged and valued. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉

And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:

  • Star the project
  • Talk about it!
  • Refer this project in your project's readme
  • Mention the project at local meetups and tell your friends/colleagues

Bug reports

Bug reports and feature suggestions must use descriptive and concise titles and be submitted to GitHub Issues. Please use the search function to make sure that you are not submitting duplicates, and that a similar report or request has not already been resolved or rejected.

Pull requests

Legal Notice

When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.

NOTE: If you want to add new features, please discuss with maintainers before coding or opening a pull request. This is to ensure that we are on same track and following our roadmap.

Please use clean, concise titles for your pull requests. We use commit squashing, so the final commit in the dev branch will carry the title of the pull request. For easier sorting in changelog, start your pull request titles using one of the verbs "Add", "Change", "Remove", or "Fix" (present tense).

Example:

Not ideal Better
Fixed markAllAsRead in RoomTimeline Fix read marker when paginating room timeline

It is not always possible to phrase every change in such a manner, but it is desired.

The smaller the set of changes in the pull request is, the quicker it can be reviewed and merged. Splitting tasks into multiple smaller pull requests is often preferable.

Also, we use ESLint for clean and stylistically consistent code syntax, so make sure your pull request follow it.

Pull requests are not merged unless all quality checks are passing. At minimum, format, lint, typecheck, and knip must all be green before a pull request can be merged. Run these locally before opening or updating a pull request:

  • npm run fmt:check
  • npm run lint
  • npm run typecheck
  • npm run knip

Release notes and versioning (Knope)

We use Knope with the Knope GitHub Bot to manage change documentation and releases. The workflow configuration lives in knope.toml.

If you have used Changesets before, Knope should feel very similar. The main difference is scope: Changesets is typically used for JavaScript repositories because it relies on package.json, while Knope is multi-language.

If you prefer, you can install the Knope CLI yourself using the official installation guide. This repo also exposes the CLI through npm scripts, so you can run npm run knope -- <subcommand> (for example: npm run knope -- document-change). Otherwise, this repo installs Knope for you via postinstall, so running npm i is enough.

Documenting a change

A changeset is a Markdown file (usually in .changeset/) that captures intent to change: the semver bump (major, minor, patch) and the user-facing release note text. Knope later combines all pending changesets to decide version bumps and generate changelog entries.

For user-facing pull requests, add one before requesting review.

CLI paths:

  • npm run document-change
  • npm run knope -- document-change
  • knope document-change (if Knope is installed locally)

All commands open an interactive prompt; fill in the package, change type, and short summary, then commit the generated change file in your PR.

Alternatively, you can document the change manually by creating a change file:

  1. Create a file named .changeset/fix-room-timeline-pagination.md (or another descriptive file name).
  2. Copy and paste this Markdown into the file:
---
sable: patch
---

Short user-facing summary of the change.
  1. Replace patch with one of: major, minor, patch, docs, or note.
  2. Edit the summary so it describes user-facing impact (not maintainer-only details).

In this repo, the internal label skips Knope's documentation check ([bot.checks].skip_labels).

Further reading:

Release flow (GitHub Bot)

Releases are driven by Knope Bot ([bot.releases].enabled = true):

  • The bot keeps an up-to-date release PR from knope/release.
  • Merging that bot release PR publishes the GitHub release.

Local validation and dry-run (optional)

Maintainers can preview behavior without changing files:

  • npm run knope -- release --dry-run

You can also validate the local Knope config with:

  • npm run knope -- --validate

For any query or design discussion, join our Matrix room.

Helpful links