diff --git a/CLAUDE.md b/CLAUDE.md index 738013c..215eace 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,6 +65,7 @@ See `.env.example` for required Cloudflare R2 configuration. 3. **Check limits**: Enforce size limits (500KB/file, 5MB/gist, 20 files) 4. **Validate inputs**: Especially for user-provided content 5. **Handle errors**: Provide clear error messages to users +6. **Follow guidelines**: See `CONTRIBUTING.md` for development workflow For detailed architecture, API specs, and data models, refer to `docs/SPEC.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..700783f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,266 @@ +# Contributing to GhostPaste + +Thank you for your interest in contributing to GhostPaste! We welcome contributions from the community. + +## ๐Ÿš€ Getting Started + +### Prerequisites + +- Node.js 20+ +- npm 10+ +- Git +- A Cloudflare account (for R2 storage testing) + +### Local Development Setup + +1. **Clone the repository** + + ```bash + git clone https://github.com/nullcoder/ghostpaste.git + cd ghostpaste + ``` + +2. **Install dependencies** + + ```bash + npm install + ``` + +3. **Set up environment variables** + + ```bash + cp .env.example .env.local + ``` + + Fill in your Cloudflare R2 credentials in `.env.local` + +4. **Run development server** + ```bash + npm run dev + ``` + +For detailed local development instructions, see [docs/LOCAL_DEVELOPMENT.md](docs/LOCAL_DEVELOPMENT.md). + +## ๐Ÿ“ Development Workflow + +### 1. Create an Issue + +Before starting work: + +- Check existing issues to avoid duplicates +- Create a new issue describing your proposed change +- Wait for maintainer feedback/approval + +### 2. Create a Branch + +```bash +git checkout main +git pull origin main +git checkout -b feat/your-feature-name +``` + +Branch naming conventions: + +- `feat/` - New features +- `fix/` - Bug fixes +- `docs/` - Documentation changes +- `refactor/` - Code refactoring +- `test/` - Test additions/changes +- `chore/` - Maintenance tasks + +### 3. Make Your Changes + +- Follow the existing code style +- Add tests for new functionality +- Update documentation as needed +- Keep commits focused and atomic + +### 4. Run Tests and Linting + +Before committing: + +```bash +npm run test # Run unit tests +npm run lint # Run ESLint +npm run typecheck # Run TypeScript checks +``` + +### 5. Commit Your Changes + +We follow conventional commits: + +```bash +git commit -m "feat: add encryption key rotation" +git commit -m "fix: resolve PIN validation issue" +git commit -m "docs: update API documentation" +``` + +### 6. Push and Create PR + +```bash +git push origin feat/your-feature-name +``` + +Then create a pull request on GitHub with: + +- Clear description of changes +- Reference to related issue(s) +- Screenshots for UI changes +- Test results + +## ๐Ÿ—๏ธ Code Guidelines + +### TypeScript + +- Use strict TypeScript settings +- Define interfaces for all data structures +- Avoid `any` types +- Document complex types + +### React/Next.js + +- Use functional components with hooks +- Follow Next.js 15 app router patterns +- Keep components small and focused +- Use shadcn/ui components when possible + +### Security + +- **NEVER** log encryption keys or sensitive data +- **NEVER** send keys to the server +- **ALWAYS** validate user input +- **ALWAYS** use HTTPS in production +- Follow zero-knowledge encryption principles + +### Edge Runtime Compatibility + +All code must be compatible with Cloudflare Workers: + +- No Node.js-specific APIs +- Use Web APIs (fetch, crypto, etc.) +- Keep bundle sizes small +- Respect CPU time limits (50ms) + +## ๐Ÿงช Testing + +### Unit Tests + +- Write tests for all utility functions +- Test error cases and edge conditions +- Use Vitest for testing +- Maintain >80% coverage for critical paths + +### Integration Tests + +- Test complete user flows +- Verify encryption/decryption +- Test API endpoints +- Check error handling + +### Manual Testing + +Before submitting PR: + +- [ ] Create a new gist +- [ ] View shared gist +- [ ] Edit with PIN +- [ ] Test expiry features +- [ ] Verify mobile responsiveness + +## ๐Ÿ“š Documentation + +### Code Documentation + +- Add JSDoc comments for public APIs +- Document complex algorithms +- Include usage examples +- Update README for new features + +### Project Documentation + +Update relevant docs: + +- `README.md` - Project overview +- `docs/SPEC.md` - Technical specifications +- `docs/TODO.md` - Mark completed tasks +- `CLAUDE.md` - AI assistant guidelines + +## ๐ŸŽฏ Pull Request Process + +1. **PR Title**: Use conventional commit format +2. **Description**: Explain what and why +3. **Testing**: Describe how you tested +4. **Screenshots**: Include for UI changes +5. **Review**: Address feedback promptly + +### PR Checklist + +- [ ] Tests pass locally +- [ ] Linting passes +- [ ] TypeScript checks pass +- [ ] Documentation updated +- [ ] No console.logs left +- [ ] No commented code +- [ ] Follows security guidelines + +## ๐Ÿ’ก Feature Requests + +We welcome feature suggestions! Please: + +- Open an issue with `[Feature Request]` prefix +- Describe the use case +- Explain expected behavior +- Consider security implications + +## ๐Ÿ› Bug Reports + +When reporting bugs: + +- Use the bug report template +- Include reproduction steps +- Provide browser/OS information +- Include error messages +- Add screenshots if applicable + +## ๐Ÿค Code of Conduct + +### Be Respectful + +- Treat everyone with respect +- Welcome newcomers +- Be patient with questions +- Give constructive feedback + +### Be Professional + +- Stay on topic +- Avoid offensive language +- Respect differing opinions +- Focus on what's best for the project + +## ๐Ÿ“ฌ Communication + +- **Issues**: Bug reports and feature requests +- **Discussions**: General questions and ideas +- **Pull Requests**: Code contributions + +## ๐Ÿ† Recognition + +Contributors will be: + +- Listed in the README +- Credited in release notes +- Thanked in commit messages + +## โ“ Questions? + +If you have questions: + +1. Check existing documentation +2. Search closed issues +3. Ask in GitHub Discussions +4. Tag @nullcoder for help + +--- + +Thank you for contributing to GhostPaste! ๐Ÿ‘ป diff --git a/README.md b/README.md index b32231a..98564b1 100644 --- a/README.md +++ b/README.md @@ -121,10 +121,12 @@ npm run deploy - [Technical Specification](docs/SPEC.md) - Detailed architecture and implementation details - [AI Development Guide](CLAUDE.md) - Guidelines for AI-assisted development - [Implementation TODO](docs/TODO.md) - Development roadmap and progress tracking +- [Contributing Guide](CONTRIBUTING.md) - How to contribute to the project +- [Local Development](docs/LOCAL_DEVELOPMENT.md) - Setting up your development environment ## ๐Ÿค Contributing -We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) (coming soon). +We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for detailed information on how to contribute to this project. 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md index 249eacc..37a30ec 100644 --- a/docs/LOCAL_DEVELOPMENT.md +++ b/docs/LOCAL_DEVELOPMENT.md @@ -186,4 +186,4 @@ For faster development of UI components, use `npm run dev` for Next.js hot reloa - Check out the [Architecture Guide](./SPEC.md) to understand the system design - Review [Security Guidelines](./SPEC.md#security-considerations) for encryption implementation -- See [Contributing Guide](../README.md#contributing) for code standards +- See [Contributing Guide](../CONTRIBUTING.md) for code standards and development workflow diff --git a/docs/TODO.md b/docs/TODO.md index 62ccc80..43ba18b 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -286,7 +286,7 @@ This document tracks the implementation progress of GhostPaste. Check off tasks - [ ] Document API endpoints - [ ] Create architecture diagrams -- [ ] Write contribution guidelines +- [x] Write contribution guidelines - [ ] Add code style guide - [ ] Create development setup guide