Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (85 loc) · 6.39 KB

CONTRIBUTING.md

File metadata and controls

125 lines (85 loc) · 6.39 KB
Raw

Gitify Contributing Guide

Hi! We're really excited that you're interested in contributing to Gitify!

Before submitting your contribution, please read through the following guide.

We also suggest you read the Project Philosophy in our documentation.

Getting Started

Tip

Optional: If you prefer to use your own OAuth credentials, you can do so by passing them as environment variables when bundling the app. This is optional as the app has some default "development" keys (use at your own discretion).

OAUTH_CLIENT_ID="123" pnpm build

To get started:

Clone the repository and install dependencies:

pnpm install

Copy the .env.template to .env and add update GITHUB_TOKEN with a GitHub Personal Access Token. This is used for fetching the latest GitHub GraphQL API schema for graphql-codegen.

GITHUB_TOKEN=<some personal access token>

Start development mode (includes GraphQL codegen and hot module reload):

pnpm dev

Tests

Tooling is unified through Vite+, which bundles the linter (oxlint), formatter (oxfmt), test runner (Vitest), and dev/build pipeline (Vite).

# Run lint, format, and type checks
pnpm check

# Auto-fix formatting and lint issues
pnpm check:fix

# Run unit tests with coverage
pnpm test

# Update vitest snapshots
pnpm test -u

Code Style & Conventions

  • Linting and formatting are configured in vite.config.ts (the lint and fmt blocks). Please run pnpm check before submitting a PR.
  • Follow existing file and folder naming conventions.
  • Keep commit messages clear and descriptive.

How to Report Bugs or Request Features

If you encounter a bug or have a feature request, please open an issue with clear steps to reproduce or a detailed description of your idea. Check for existing issues before creating a new one.

Releases

Releases are automated with release-please. There is no release branch and no manual version bump.

  1. Merge changes into main. Use Conventional Commits for PR titles (feat:, fix:, docs:, chore(deps):, ...). The commit type decides the version bump and the changelog section it lands in.
  2. Review the release PR. release-please keeps an open chore: release X.Y.Z pull request up to date as commits land. It bumps the version in package.json, regenerates CHANGELOG.md, and updates sonar.projectVersion in sonar-project.properties. Check the Renovate Dependency Dashboard for any dependency updates you want to include first.
  3. Merge the release PR when you are ready to ship. Merging is the "go" decision. GitHub Actions then automatically:
  • builds, signs, and notarizes the app on macOS, Windows, and Linux,
  • attaches the assets to the release that release-please drafted, and
  • publishes the release (creating the vX.Y.Z tag), which redeploys the website and triggers the automatic Homebrew cask bump (workflow runs ~3 hours).
  1. (Optional) Update milestones:
  • Edit the current Milestone: add a link to the release notes, set the due date to the release date, and close it.
  • Create a New Milestone for the next release cycle.

Design Guidelines

  1. Use sentence case where possible
  2. Use GitHub's Octicons for iconography

Project Philosophy

This project is a tool for monitoring new notifications from supported Git forges. It's not meant to be a full-featured forge client. We want to keep it simple and focused on that core functionality. We're happy to accept contributions that help us achieve that goal, but we're also happy to say no to things that don't. We're not trying to be everything to everyone.

Multi-forge support

Gitify supports notifications from multiple Git forges. New forges may be added under the following conditions:

  • Adapter-based: the forge is implemented behind the ForgeAdapter interface in src/renderer/utils/forges/. No forge-specific branching outside the adapter module.
  • Designated maintainer: every forge has at least one named maintainer in MAINTAINERS.md who owns triage and CI for that adapter.
  • Capability-honest UI: features unsupported by a forge (e.g. mark-as-done) must hide gracefully, not silently no-op.
  • No core-platform churn: Octicons, Octokit, and the Primer Design System remain in place. Octokit is scoped to the GitHub adapter; other adapters use plain fetch.

Currently supported forges: GitHub (Cloud, Enterprise Server, Enterprise Cloud with Data Residency) and Gitea (incl. Forgejo, Codeberg).

Things we won't do

  • Operating-system level features
    • Do not disturb, including on schedules. #416 (comment)
    • Persistent notifications like #281. e.g. macOS has Alerts, instead of Banners, which makes them persistent
  • Seeing past notifications. This is a tool for monitoring new notifications, not seeing old ones, which can be seen at https://github.com/notifications.
  • Specific UX/UI changes that add options and/or visual complexity for minor workflow improvements. e.g. #358, #411 and #979
  • UI for something that isn't core to Gitify, and/or can be trivially done another way. e.g. #476 and #221
  • Add a forge adapter without a designated maintainer who will own it long-term.