How to Contribute

we use a fork-based contribution workflow.

How to Contribute

We use a fork-based contribution workflow. The main branch is protected for production. All external contributions go through the develop branch.

Contribution Flow: Fork → Clone → Branch → Commit → Push → Pull Request → Review → Merge

---

Step 1: Fork the Repository

Go to https://github.com/betterbugs/dev-tools and click the Fork button in the top-right corner. This creates your own copy of the repository.

---

Step 2: Clone Your Fork Locally

git clone https://github.com/YOUR-USERNAME/dev-tools.git
cd dev-tools

Add the upstream remote to keep your fork synced:

git remote add upstream https://github.com/betterbugs/dev-tools.git
git fetch upstream

---

Step 3: Create a Feature Branch

Always work on a new branch, never directly on develop or main:

git checkout develop
git pull upstream develop
git checkout -b feature/your-feature-name

Branch naming:

• feature/tool-name — New tool

• fix/bug-description — Bug fix

• docs/description — Documentation

• refactor/component-name — Code improvements

---

Step 4: Make Your Changes

Adding a new tool? Read the Feature and Module Structure guide.

General guidelines:

• Follow the Google JavaScript Style Guide

• Keep components focused and reusable

• Use TypeScript types (avoid any)

• Reuse existing UI components from app/components/ui/

• Add shared logic to app/libs/helpers.tsx, not duplicated in components

Building Tools with Network Features?

Network requests are completely fine! We're building tools for developers.

All of these are acceptable:

• Fetching data from public APIs

• AI features using user-provided API keys

• Tools that enhance with network features

• Integrations with external services

When using network features, follow these best practices:

1. Make it optional and graceful

• Core tool works without the API/network

• If API is unavailable, feature gracefully disables itself

• Show clear error messages ("API key missing" or "Network unavailable")

• Provide fallbacks or helpful UI states

2. Document clearly

• Which APIs are needed

• How to get API keys (if required)

• What happens if the feature is unavailable

• Example: "This feature requires an OpenAI API key. If not provided, the tool still works for basic conversion."

3. Environment variables

• Use env vars for API keys and sensitive data

• Document required env vars in README or tool description

• If env var is missing, the feature should disable gracefully

• Example: If NEXT_PUBLIC_OPENAI_KEY is missing, button says "Configure API key to unlock AI features"

Example implementation:

// Tool works without API
const handleConvert = () => {
  const basicResult = convertBasic(input); // Always works
  setOutput(basicResult);
};

// Enhanced with API if available
const handleEnhancedConvert = async () => {
  if (!process.env.NEXT_PUBLIC_API_KEY) {
    showMessage("Configure API key to unlock enhanced features");
    return;
  }
  
  try {
    const enhanced = await callAPI(input);
    setOutput(enhanced);
  } catch (err) {
    showMessage("API unavailable, using basic conversion");
    setOutput(convertBasic(input));
  }
};

Offline-Safe Tools

Most of our current tools work locally (recommended):

• Process data entirely in the browser

• No network calls needed

• Works fully offline

• Best user experience

Examples: JSON formatter, base64 encoder, text converters, CSS minifier, etc.

---

Step 5: Commit with Conventional Commits

We follow Conventional Commits for consistent, readable history.

git add .
git commit -m "type(scope): description"

Types:

• feat: — New feature or tool

• fix: — Bug fix

• docs: — Documentation

• refactor: — Code cleanup

• style: — Code formatting

• test: — Tests

Examples:

git commit -m "feat(tools): add yaml-to-json converter"
git commit -m "fix(json-formatter): handle empty input gracefully"
git commit -m "docs: add feature structure guide"
git commit -m "refactor(helpers): simplify text conversion functions"

---

Step 6: Check Code Quality

Before pushing, run the linter:

npm run lint

Fix any warnings or errors. Your code must pass linting before opening a PR.

---

Step 7: Push to Your Fork

git push origin feature/your-feature-name

---

Step 8: Open a Pull Request

Go to https://github.com/betterbugs/dev-tools. You'll see a prompt to open a PR. Click Compare & pull request.

Important: Make sure you're merging INTO develop, not main.

Fill out the PR Template:

## Description
_Give a summary of what you changed_

Fixes #[ISSUE_NUMBER]

## Type of Change
- [ ] New tool
- [ ] Bug fix
- [ ] Documentation
- [ ] Code improvement

## Feature Label
(Choose one - we'll add this label)
- [ ] offline-safe (works fully offline)
- [ ] network-enabled (uses APIs)
- [ ] experimental (new, may change)
- [ ] requires-api-key (user must configure key)

## Dependencies
_Any new packages or APIs used?_

## For Tools with Network Features
- What API/service is used?
- How does it fail gracefully if unavailable?
- Any env vars needed? (List them)
- Does the core tool work without this feature?

## Testing
- [ ] Tested locally at http://localhost:3000
- [ ] Ran `npm run lint` - no errors
- [ ] Code follows Google JavaScript Style Guide
- [ ] No UI/UX issues

## Future Improvements
_Optional: improvements for the future_

## Screenshots
_Add screenshots if relevant_

Example PR:

## Description
Adds a JSON to YAML converter tool for developers.

## Type of Change
- [✓] New tool

## Feature Label
- [✓] offline-safe (works fully offline)

## Testing
- [✓] Tested locally
- [✓] Lint passes
- [✓] No UI issues

PR with Network Features:

## Description
Adds AI-powered code comment generator using OpenAI API.

## Type of Change
- [✓] New tool

## Feature Label
- [✓] network-enabled
- [✓] requires-api-key

## For Tools with Network Features
- API: OpenAI API
- Graceful failure: If key missing, tool shows message "Configure OpenAI API key to enable AI features". Basic code generation still works.
- Env var: `NEXT_PUBLIC_OPENAI_KEY`
- Core tool: Yes, basic code formatting works without API

## Testing
- [✓] Tested without API key - graceful failure works
- [✓] Tested with API key - feature works
- [✓] Lint passes
- [✓] No UI issues

---

Step 9: Code Review

The core team reviews your PR. They may ask for:

• Code changes

• Additional documentation

• Clarification on network features

• Screenshots or demos

Respond to feedback:

1. Read the comments

2. Make requested changes

3. Commit and push (same branch)

4. The PR updates automatically

Ask questions in the PR comment thread if something isn't clear!

---

Step 10: Merge

Once approved, a maintainer merges your PR into develop.

Cleanup your local branches:

git checkout develop
git pull upstream develop
git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name

Your code is now part of the project! 🎉

Later, the core team promotes changes from develop to main for production releases.

---

Important: Feature Labeling

When your PR is merged, we'll label it with one of these tags so users understand what they're getting:

🟢 offline-safe — Works fully offline, no network calls 🔵 network-enabled — Uses APIs or external services 🟡 experimental — New, may change or be removed 🟠 requires-api-key — User must configure API credentials

This builds trust. Users choose knowingly.

---

Key Documents

Before contributing, read:

1. CODE_OF_CONDUCT.md — Community standards

2. CONTRIBUTING.md — Detailed guidelines

3. SECURITY.md — Security vulnerabilities → email [email protected]

4. Feature and Module Structure — How tools are built

5. PWA and Offline Behavior — Understanding offline support

---

Need Help?

• Discord: Join (fastest!)

• Ask in your PR: Comment with questions

• Check issues: Existing discussions may help

• Read docs: README, CONTRIBUTING, guides

---

Quick Reference Checklist

Before opening a PR:

• Forked the repo

• Cloned my fork locally

• Created feature branch off develop

• Read CODE_OF_CONDUCT.md

• Read CONTRIBUTING.md

• Followed Google JavaScript Style Guide

• Ran npm run lint — no errors

• Tested locally at http://localhost:3000

• If using network features: documented APIs and graceful failure

• If using env vars: documented and tested with/without them

• Used Conventional Commits

• PR targets develop (not main)

• Filled out PR Template

• Selected appropriate feature label

---

Ready? Pick an open issue or propose a feature. Let's build!