# Contributing to One File Tools
Thank you for your interest in contributing! Whether you’re here through **SSoC (Social Summer of Code)**, Hacktoberfest, or just because you love building useful things, you’re welcome here.
This guide will walk you through everything you need to know.
---
## Table of Contents
- [Philosophy](#philosophy)
- [Types of Contributions](#types-of-contributions)
- [Before You Start](#before-you-start)
- [Building a New Tool](#building-a-new-tool)
- [Enhancing an Existing Tool](#enhancing-an-existing-tool)
- [Tool Requirements](#tool-requirements)
- [File Naming Convention](#file-naming-convention)
- [Code Style](#code-style)
- [Pull Request Process](#pull-request-process)
- [Review & Labels](#review--labels)
- [SSoC Contributors](#ssoc-contributors)
- [Need Help?](#need-help)
---
## Philosophy
Every tool in this repository follows one core principle:
> **One tool. One file. Open and use.**
This means:
- Each tool lives in a **single `.html` file**.
- It must work by simply **opening the file in a browser**.
- **No build step**, no `npm install`, no framework.
- Code should be **readable**, someone learning web development should be able to understand it.
- It should work **offline** whenever possible.
---
## Types of Contributions
Every pull request should fall into one of these categories:
| Type | Description | Label |
| ----------------- | ------------------------------------------------------------------------------- | ----------------- |
| **New Tool** | Build a tool from the [Ideas Board](ReadMe.md#ideas-board) or propose your own. | `Easy` / `Medium` |
| **Enhancement** | Improve an existing tool - UI, UX, features, accessibility, performance. | `Easy` / `Medium` |
| **Bug Fix** | Fix something that’s broken. | `Easy` / `Medium` |
| **Documentation** | Improve docs, add code comments, fix typos. | `Easy` |
---
## Before You Start
1. **Check existing issues:** Someone may already be working on the same tool.
2. **Check existing PRs:** Avoid duplicate effort
3. **Claim your issue:** Comment on the issue saying you’d like to work on it. Wait for assignment before starting
4. **One tool per PR:** Keep your pull requests focused. Don’t bundle multiple tools into one PR
### Proposing a new idea
If your tool idea isn’t on the Ideas Board:
1. Open a [New Tool Idea](https://github.com/praveenscience/One-File-Tools/issues/new?template=new-tool-idea.yml) issue using the issue template.
2. Fill in the tool name, filename, category, description, features, and suggested difficulty.
3. The maintainer will review it, assign a difficulty label, and add it to the board.
For bug reports or enhancements to existing tools, use the appropriate [issue template](https://github.com/praveenscience/One-File-Tools/issues/new/choose).
---
## Building a New Tool
### Step 1 — Fork & clone
```bash
git clone https://github.com/YOUR-USERNAME/One-File-Tools.git
cd One-File-Tools
```
### Step 2 — Create a branch
#### Creating a New Tool
```bash
git checkout -b add/your-tool-name
git checkout -b new/json-formatter
```
Use the `add/` / `new/` prefix for new tools.
#### Enhancing an Existing Tool
```bash
git checkout -b feat/json-formatter
```
Use the `feat/` for enhancements.
#### Fixing Bug in an Existing Tool
```bash
git checkout -b fix/json-formatter
```
Use the `fix/` for bug fixes.
### Step 3 — Create or Edit your file
```bash
touch tools/your-tool-name.html
vim tools/your-tool-name.html
```
### Step 4 — Build your tool
Use the template below as a starting point:
```html
Tool Name — One File Tools
Tool Name
A brief description of what this tool does.
```
### Step 5 — Test
- Open the file directly in your browser (`open tools/your-tool-name.html`).
- Test on Chrome and Firefox at minimum.
- Test on mobile (resize your browser or use DevTools responsive mode).
- Check for console errors.
- Verify it works offline (disconnect and reload).
### Step 6 — Submit
```bash
git add tools/your-tool-name.html
git commit -m "Add: your-tool-name"
git push origin add/your-tool-name
```
Then open a Pull Request following the [PR process below](#pull-request-process).
---
## Enhancing an Existing Tool
Enhancements are valuable contributions! Some examples:
- Adding **dark mode** support.
- Improving **responsive design** for mobile.
- Adding **keyboard shortcuts**.
- Improving **accessibility** (ARIA labels, focus management, screen reader support).
- Adding **copy to clipboard** functionality.
- Better **error handling** and user feedback.
- Performance improvements.
- Adding **export** options (download, share).
### Branch naming for enhancements
```bash
git checkout -b feat/tool-name-what-you-changed
# Example: improve/json-formatter-dark-mode
```
---
## Tool Requirements
### Must have
- [ ] Single `.html` file, all HTML, CSS, and JS in one file.
- [ ] Works by opening the file in a browser, no server required.
- [ ] No build step.
- [ ] Responsive design, works on desktop and mobile.
- [ ] No console errors.
- [ ] No tracking scripts, analytics, or advertisements.
- [ ] Has a clear title and description in the page.
- [ ] Includes a link back to the repo in the footer.
- [ ] Prettier formatted in the given configuration.
### Should have
- [ ] Dark mode support (at minimum via `prefers-color-scheme`).
- [ ] Keyboard accessible, all interactive elements reachable via Tab.
- [ ] Semantic HTML (``, ``, `