Back to Open Source

Contribution Guidelines

How we contribute

The reference guide for contributing to any Omisai open source project. Language-agnostic, written plainly, and useful at every seniority level.

Applies to all repositories  ·  Last updated 2026

01Contributing

Contributions are welcome and will be fully credited.

Please read and understand this guide before creating an issue or pull request. A few minutes upfront saves hours of back-and-forth during review.

02Standards & principles

These principles apply to all languages and all repositories. Individual repositories may extend them — never relax them.

01
Prefer clarity over cleverness
Write code that is easy to read, review, and maintain. Straightforward solutions beat surprising ones. If a reviewer has to pause to decode what a line does, it needs a rename or a comment.
02
Keep things DRY — Don't Repeat Yourself
Remove unnecessary duplication when it improves maintainability. But avoid premature abstraction: a well-named function copied once is often cleaner than an over-generalized utility.
03
Follow clean coding practices
Use descriptive names, keep functions small and focused, write cohesive modules, favor explicit behavior over magic, and stay consistent with the conventions already present in the repository.
04
SOLID & single responsibility
Each module, class, or function should do one thing well. Separation of concerns makes code easier to test, debug, and evolve independently without unintended side effects.
05
Preserve public API stability
We follow SemVer v2.0.0. Breaking public interfaces without a major version bump is not acceptable. Deprecate first; remove in a future major release.
06
Tests and docs are part of the change
A pull request without tests or documentation updates for changed behavior is incomplete. Include them upfront rather than waiting for reviewers to ask.

03Etiquette

This project is open source, and as such, the maintainers give their free time to build and maintain the source code held within. They make the code freely available in the hope that it will be of use to other developers. It would be extremely unfair for them to suffer abuse or anger for their hard work.

Please be considerate towards maintainers when raising issues or presenting pull requests. Let's show the world that developers are civilized and selfless people.

It's the duty of the maintainer to ensure that all submissions to the project are of sufficient quality to benefit the project. Many developers have different skillsets, strengths, and weaknesses. Respect the maintainer's decision, and do not be upset or abusive if your submission is not used.

04Viability

When requesting or submitting new features, first consider whether it might be useful to others. Open source projects are used by many developers, who may have entirely different needs to your own. Think about whether your feature is likely to be used by other users of the project.

A feature that solves your specific problem may not belong in the core library if it doesn't align with the project's direction. In those cases, a separate package or a fork might be the right solution — and that's completely fine.

05Procedure

Before filing an issue

  • Attempt to replicate the problem to ensure it was not a coincidental incident.
  • Check to make sure your feature suggestion is not already present within the project.
  • Check the pull requests tab to ensure the bug does not already have a fix in progress.
  • Check the pull requests tab to ensure the feature is not already in progress.

Before submitting a pull request

  • Check the codebase to ensure your feature or fix does not already exist.
  • Check the open pull requests to ensure nobody has already submitted the same change.
  • Attach relevant automated tests covering the new or changed behavior.
  • Update README.md and any other affected documentation as part of the same PR.
  • Scope the pull request to one coherent feature or fix only.
  • Squash intermediate work commits so each commit in the final branch is meaningful.

06Pull requests

  1. 01

    One pull request per feature

    If you want to do more than one thing, send multiple pull requests. Mixing unrelated changes makes review difficult and history hard to bisect.

  2. 02

    Tests are required

    Every change must ship with automated tests. If the behavior is not tested, it is not considered done. Unit tests, integration tests, or both — whichever is appropriate.

  3. 03

    Keep documentation in sync

    Any user-facing or API behavior change must be reflected in README.md and other relevant docs, inside the same pull request.

  4. 04

    Send coherent history

    Each commit in your pull request must be meaningful on its own. If you made intermediate commits while experimenting, squash them before submitting.

  5. 05

    Use conventional commit messages

    All commits must follow the Conventional Commits specification. See the section below if you are not already familiar with it.

  6. 06

    Expect iteration

    Quality and long-term maintainability matter more than speed. Reviewers may ask for changes — that is part of collaborative development, not a rejection.

07Conventional commits

conventionalcommits.org

All commits must follow the Conventional Commits specification. This enables automated changelogs, semantic release tooling, and makes history easy to scan during review.

Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Examples

feat(auth): add token refresh support
fix(api): prevent nil response on empty payload
docs(readme): clarify installation steps
refactor(parser): extract token validation into helper
test(user): add edge case tests for empty username
chore(deps): upgrade axios to v1.6.0
ci(github-actions): add lint step to pull request workflow

# Breaking change — note the "!" and BREAKING CHANGE footer
feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: /v1/users and /v1/posts have been removed.
Migrate to /v2/users and /v2/posts.

Commit types

featA new feature for the user
fixA bug fix for the user
docsDocumentation-only changes
styleFormatting, missing semicolons, etc.
refactorCode change that is neither a fix nor a feature
perfPerformance improvement
testAdding or correcting tests
choreBuild process, tooling, or dependency updates
ciChanges to CI configuration and scripts
revertReverts a previous commit
Not familiar yet? Read the full spec at conventionalcommits.org before your first pull request. It takes about 10 minutes.

08Semantic versioning

semver.org

We follow Semantic Versioning v2.0.0 for all published packages. Given a version number MAJOR.MINOR.PATCH, increment:

SegmentWhen to increment
MAJORIncompatible public API change
MINORNew backward-compatible feature
PATCHBackward-compatible bug fix
Breaking changes need a MAJOR bump. If your change removes, renames, or alters a public API in a backward-incompatible way, it must result in a new major version. Deprecate first; remove in a future major release.

09Language rules

This guide is intentionally language-agnostic. Each language ecosystem has established conventions contributors are expected to follow. Repository-specific rules always take precedence.

js / ts

JavaScript / TypeScript

  • Match the repository runtime, formatter (Oxfmt), and linter (Oxlint) setup before opening a pull request.
  • Prefer explicit types. Avoid `any`; use `unknown` when the type is genuinely unknown and narrow it explicitly.
  • Keep modules focused and avoid mixing unrelated responsibilities in a single file.
  • Add or update tests (Vitest or the runner configured for the repo) for every behavior change.
php

PHP

  • Follow PSR-12 coding standard unless the repository documents a stricter convention.
  • Prefer clear class boundaries, explicit contracts (interfaces), and consistent naming conventions.
  • Keep public APIs stable. Deprecate first; remove later. Document the deprecation clearly.
  • Add or update tests (PestPHP or the framework configured for the repo) for every behavior change.
go

Go

  • Follow idiomatic Go style. Run `gofmt` and `go vet` before submitting.
  • Favor small packages, simple interfaces, and explicit error handling. Avoid global state.
  • Keep exported APIs intentional and stable. Breaking changes require a major version.
  • Add or update automated tests and keep example code accurate whenever behavior changes.

10Final checklist

Run through this before marking your pull request as ready for review.

  1. 01The change is genuinely useful beyond a single narrow use case.
  2. 02The code is readable, clean, and consistent with the rest of the repository.
  3. 03Automated tests are attached and passing for the affected behavior.
  4. 04Documentation has been updated for every user-facing or public API change.
  5. 05All commit messages follow the Conventional Commits specification.
  6. 06The pull request addresses exactly one coherent feature or fix.
  7. 07Intermediate work commits have been squashed into a meaningful history.
Browse repositoriesOpen Source overview