# 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**](https://docs.betterbugs.io/contributing-to-betterbugs/design-of-our-code/feature-and-module-structure-tour) 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 . 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 4. [**Feature and Module Structure**](https://docs.betterbugs.io/contributing-to-betterbugs/design-of-our-code/feature-and-module-structure-tour) — How tools are built 5. [**PWA and Offline Behavior**](https://docs.betterbugs.io/contributing-to-betterbugs/design-of-our-code/pwa-and-offline-behavior) — 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 * [ ] 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!