# How to Contribute

## 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

***

### Branch Strategy

**Branch purposes:**

* **main**: Always reflects the latest stable and released code
* **develop**: Contains accepted changes that will be part of the next release

**For all contributors:**

* Create a new branch from `develop`
* Open pull requests against `develop` (not `main`)

**For regular contributors:** If your work depends on unreleased features or changes, base your work directly on `develop`. Pull requests merged into `develop` are considered accepted for now, but remain under maintainer control. Our team decides which changes move from `develop` to `main` for release, and may revert or modify any merged code if needed.

### Step 1: Fork the Repository

Go to [`https://github.com/betterbugs/dev-tools`](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

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

Add the upstream remote to keep your fork synced:

```bash
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`:

```bash
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**](/contributing-to-betterbugs/design-of-our-code/feature-and-module-structure-tour.md) guide.

**General guidelines:**

* Follow the [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
* 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:**

```typescript
// 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](https://www.conventionalcommits.org/) for consistent, readable history.

```bash
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:**

```bash
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:

```bash
npm run lint
```

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

***

### Step 7: Push to Your Fork

```bash
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:**

```markdown
## 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:**

```markdown
## 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:**

```markdown
## 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:**

```bash
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:

{% hint style="success" %}
🟢 **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
{% endhint %}

This builds trust. Users choose knowingly.

***

### Key Documents

Before contributing, read:

1. [CODE\_OF\_CONDUCT.md](https://github.com/betterbugs/dev-tools/blob/main/CODE_OF_CONDUCT.md) — Community standards
2. [CONTRIBUTING.md](https://github.com/betterbugs/dev-tools/blob/main/CONTRIBUTING.md) — Detailed guidelines
3. [SECURITY.md](https://github.com/betterbugs/dev-tools/blob/main/SECURITY.md) — Security vulnerabilities → email <dev@betterbugs.io>
4. [**Feature and Module Structure**](/contributing-to-betterbugs/design-of-our-code/feature-and-module-structure-tour.md) — How tools are built
5. [**PWA and Offline Behavior**](/contributing-to-betterbugs/design-of-our-code/pwa-and-offline-behavior.md) — Understanding offline support

***

### Need Help?

* **Discord:** [Join](https://discord.com/invite/HF8XjwVtPh) (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](https://github.com/betterbugs/dev-tools/blob/main/CODE_OF_CONDUCT.md)
* [ ] Read [CONTRIBUTING.md](https://github.com/betterbugs/dev-tools/blob/main/CONTRIBUTING.md)
* [ ] Followed [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
* [ ] 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](https://github.com/betterbugs/dev-tools/issues) or [propose a feature](https://github.com/betterbugs/dev-tools/issues/new?template=feature_request.md). Let's build! <img src="/files/fyKfPVNSFxHAtzPEMRDU" alt="" data-size="line">


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.betterbugs.io/contributing-to-betterbugs/how-to-contribute.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.