Skip to content

Development Workflow

Jump to bottom
Shamik Karkhanis edited this page Jan 28, 2026 · 4 revisions

Development Workflow

This guide outlines the standard workflow for contributing to capy-discord, including how to work with Linear issues, manage branches, and submit Pull Requests.

1. Linear Integration & Branching

We use Linear for issue tracking. Every unit of work (feature, bug fix, chore) should correspond to a Linear issue.

Starting a New Task

  1. Assign the Issue: In Linear, assign the issue to yourself and move it to "In Progress".
  2. Create a Branch:
    • Automatic (Recommended): Click the "Copy branch name" button in the Linear issue (usually looks like feature/issue-id-title).
    • Manual: If creating manually, use the format: feature/CAPY-123-short-description.
      • Example: feature/CAPY-42-add-login-command

Branch Naming Convention

If not using the Linear generated name, please follow these prefixes:

  • feature/: New features
  • fix/: Bug fixes
  • refactor/: Code restructuring without behavior changes
  • docs/: Documentation updates
  • test/: Adding missing tests
# Create and switch to the new branch
git checkout -b feature/CAPY-42-add-login-command

2. Committing Changes

We follow the Conventional Commits specification to keep our history clean and readable.

Commit Message Format

<type>(<scope>): <subject>
  • type: feat, fix, docs, style, refactor, test, chore
  • scope: (Optional) The module or file affected (e.g., auth, utils)
  • subject: Short, imperative description (lowercase, no period at end)

Examples

  • feat(auth): add discord oauth login flow
  • fix(utils): resolve null pointer in date parser
  • docs: update installation guide for macos

Best Practices

  • Keep commits atomic (one logical change per commit).
  • Reference the Linear issue ID in the PR description, not necessarily in every commit message (though Fixes CAPY-123 in the footer is helpful).

3. Opening a Pull Request (PR)

Once your work is ready for review:

  1. Push your branch: 
    git push -u origin your-branch-name
  2. Open PR on GitHub: Go to the repository URL. GitHub usually detects the new branch and offers a "Compare & pull request" button.
  3. Fill out the Template:
    • Base Branch: All PRs should be merged into develop.
    • Title: Use a clear, descriptive title (similar to commit messages).
    • Description: Link the Linear issue (e.g., Fixes CAPY-123 or just CAPY-123 so Linear tracks it).
    • Reviewers: You must add Shamik and Jason as reviewers. uv run task lint.

4. Review & Merge

  1. Verify CI Checks: Look at the bottom of your PR. All checks must be green (passing). If any fail (Linting, Tests, Build), click "Details" to investigate and fix them before requesting a review.
  2. Code Review: Address comments from team members.
  3. Merge: Once approved and all checks pass, squash and merge into develop.

Tip: Always sync with develop before opening your PR to avoid conflicts!

git checkout develop
git pull
git checkout your-branch-name
git rebase develop

Clone this wiki locally