Skip to content

Update CONTRIBUTING.md #606

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+23 −4
Open

Update CONTRIBUTING.md #606

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 23 additions & 4 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ Thank you for your interest in contributing to OpenCut! This document provides g

1. Fork the repository
2. Clone your fork locally
```bash
git clone https://github.com/<your-username>/opencut.git
```
Comment on lines +20 to +22
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Fix fork clone URL casing and add repo cd step

Use the canonical repo name and guide contributors into the repository directory after cloning.

-   git clone https://github.com/<your-username>/opencut.git
+   # HTTPS
+   git clone https://github.com/<your-username>/OpenCut.git
+   # or SSH
+   git clone [email protected]:<your-username>/OpenCut.git
+   cd OpenCut
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```bash
git clone https://github.com/<your-username>/opencut.git
```
🤖 Prompt for AI Agents 
In .github/CONTRIBUTING.md around lines 20 to 22, the fork clone URL uses
incorrect casing and is missing the step to change into the repository
directory; update the clone command to use the canonical repo name
(https://github.com/<your-username>/OpenCut.git) and add an immediate `cd
OpenCut` instruction after cloning so contributors are guided into the
repository folder.

3. Navigate to the web app directory: `cd apps/web`
4. Copy `.env.example` to `.env.local`:

Expand All @@ -31,7 +34,10 @@ Thank you for your interest in contributing to OpenCut! This document provides g
Copy-Item .env.example .env.local
```

5. Install dependencies: `bun install`
5. Install dependencies: We use Bun as our package manager.
From the project root: `bun install`
If you prefer, you can also use npm or pnpm, but Bun is the recommended option.

6. Start the development server: `bun run dev`

> **Note:** If you see an error like `Unsupported URL Type "workspace:*"` when running `npm install`, you have two options:
Expand All @@ -48,6 +54,9 @@ Thank you for your interest in contributing to OpenCut! This document provides g
- Performance optimizations
- Bug fixes in existing functionality
- UI/UX improvements
- Improve accessibility (keyboard navigation, screen reader support)
- Write or enhance unit and integration tests
- Improve error messages and logging
- Documentation and testing

**⚠️ Areas to Avoid:**
Expand Down Expand Up @@ -152,27 +161,37 @@ If you're unsure whether your idea falls into the preview category, feel free to
4. Run the linter: `bun run lint`
5. Format your code: `bunx biome format --write .`
6. Commit your changes with a descriptive message
7. Push to your fork and create a pull request
7. Rebase your branch against main before opening a PR
8. Push to your fork and create a pull request
9. Look for GitHub issues tagged with good first issue if you’re new

## Code Style

- We use Biome for code formatting and linting
- Run `bunx biome format --write .` from the `apps/web` directory to format code
- Run `bun run lint` from the `apps/web` directory to check for linting issues
- Follow the existing code patterns
- Use consistent naming conventions for variables, components, and files
- Write self-documenting code but add comments where clarity is needed
- Tests should follow the same conventions (framework: Jest/Vitest, check repo for current usage)
- Aim for sufficient test coverage where relevant
Comment on lines +174 to +177
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

🧩 Analysis chain

Resolve test framework ambiguity (Jest vs Vitest)

Specify the actual framework used to avoid confusion.

-• Tests should follow the same conventions (framework: Jest/Vitest, check repo for current usage)
+• Tests should follow the same conventions (framework: <Jest or Vitest> — see package.json/scripts)

Run this to detect which framework is in use:

🏁 Script executed:

#!/bin/bash
# Inspect test tooling across the repo
fd -g package.json -a -E "node_modules" | while read -r f; do
  echo "== $f =="
  jq -r '.scripts.test?, .devDependencies?.jest, .devDependencies?.vitest, .devDependencies?.biome' "$f" 2>/dev/null
done | rg -nP 'jest|vitest|biome|test'

Length of output: 0

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail
echo "Searching for package.json files..."
# prefer fd when available
if command -v fd >/dev/null 2>&1; then
  mapfile -t pkgs < <(fd -HI -t f -e json package.json || true)
else
  mapfile -t pkgs < <(find . -type f -iname package.json -not -path '*/node_modules/*' 2>/dev/null || true)
fi

if [ "${#pkgs[@]}" -eq 0 ]; then
  echo "NO_PACKAGE_JSON_FOUND"
  exit 0
fi

for p in "${pkgs[@]}"; do
  echo "== $p =="
  if command -v jq >/dev/null 2>&1; then
    jq -r '{
      testScript: (.scripts.test // "<no test script>"),
      hasJest: ((.dependencies? // {}) | has("jest")) or ((.devDependencies? // {}) | has("jest")),
      hasVitest: ((.dependencies? // {}) | has("vitest")) or ((.devDependencies? // {}) | has("vitest")),
      jestVersion: (.dependencies.jest // .devDependencies.jest // null),
      vitestVersion: (.dependencies.vitest // .devDependencies.vitest // null)
    }' "$p" || cat "$p"
  else
    echo "jq not found; printing file head:"
    sed -n '1,120p' "$p"
  fi
done

echo "Searching repository for Vitest/Jest references and config files (excluding node_modules)..."
if command -v rg >/dev/null 2>&1; then
  rg -n --hidden --no-ignore -S --glob '!node_modules' '(^|\W)(vitest|jest)(\W|$)' || true
else
  grep -RIn --exclude-dir=node_modules -E '(^|\W)(vitest|jest)(\W|$)' . || true
fi

echo "Looking for typical config files in repo root..."
for cfg in vitest.config.ts vitest.config.js vitest.config.mjs vite.config.ts vite.config.js jest.config.js jest.config.ts jest.config.cjs; do
  [ -f "$cfg" ] && echo "FOUND_CONFIG: $cfg"
done

Length of output: 92

🏁 Script executed:

#!/usr/bin/env bash
set -eu
echo "Searching for package.json files..."
tmp="$(mktemp)"
find . -type f -name package.json -not -path '*/node_modules/*' -print0 > "$tmp"
if [ ! -s "$tmp" ]; then
  echo "NO_PACKAGE_JSON_FOUND"
  rm -f "$tmp"
  exit 0
fi

while IFS= read -r -d '' p; do
  echo "== $p =="
  if command -v jq >/dev/null 2>&1; then
    jq -r '
      "testScript: " + (.scripts.test // "<no test script>"),
      "hasJest: " + ( ((.dependencies? // {}) | has("jest")) or ((.devDependencies? // {}) | has("jest")) | tostring ),
      "hasVitest: " + ( ((.dependencies? // {}) | has("vitest")) or ((.devDependencies? // {}) | has("vitest")) | tostring ),
      "jestVersion: " + ((.dependencies.jest // .devDependencies.jest) // "null"),
      "vitestVersion: " + ((.dependencies.vitest // .devDependencies.vitest) // "null")
    ' "$p" || sed -n '1,200p' "$p"
  else
    echo "jq not available; showing package.json head:"
    sed -n '1,200p' "$p"
  fi
done < "$tmp"
rm -f "$tmp"

echo
echo "Searching repository for 'vitest' or 'jest' references (excluding node_modules)..."
if command -v rg >/dev/null 2>&1; then
  rg -n --hidden --no-ignore -S --glob '!node_modules' '(^|\W)(vitest|jest)(\W|$)' || true
else
  grep -RIn --exclude-dir=node_modules -E '(^|\W)(vitest|jest)(\W|$)' . || true
fi

echo
echo "Checking for common config files in repo root..."
for cfg in vitest.config.ts vitest.config.js vitest.config.mjs vite.config.ts vite.config.js jest.config.js jest.config.ts jest.config.cjs; do
  [ -f "$cfg" ] && echo "FOUND_CONFIG: $cfg"
done

Length of output: 833

Specify test framework in CONTRIBUTING.md — no Jest/Vitest detected

Scanned package.json files (./package.json, ./apps/web/package.json, ./packages/auth/package.json, ./packages/db/package.json): none define a test script or list jest/vitest; update .github/CONTRIBUTING.md (lines 174–177) to name the repo's test framework or remove the “Jest/Vitest” hint and point contributors to the actual package.json test scripts or the chosen framework.

🤖 Prompt for AI Agents 
.github/CONTRIBUTING.md lines 174–177: the contribution guide currently
references "Tests should follow the same conventions (framework: Jest/Vitest,
check repo for current usage)" but no Jest/Vitest usage or test script exists in
package.json files; update these lines to either state the actual test framework
used in this repo (and the canonical test script path) if there is one, or
remove the "Jest/Vitest" hint and replace it with a directive telling
contributors to run the repository test via the package.json test script(s)
(e.g., "See package.json test script in the project root or package folder")
and/or link to how to discover the framework (npm/yarn pnpm test or check
package.json), so the CONTRIBUTING guidance matches the repo configuration.


## Pull Request Process

1. Fill out the pull request template completely
2. Link any related issues
3. Ensure CI passes
4. Request review from maintainers
5. Address any feedback
4. Run tests locally before pushing
5. Update documentation if features or setup change
6. Request review from maintainers
7. Address any feedback

## Community

- Be respectful and inclusive
- Follow our Code of Conduct
- Help others in discussions and issues
- Maintainers may take a few days to respond — please be patient
- Feel free to review other contributors’ PRs and leave constructive feedback

Thank you for contributing!