xixu-me
8afa94767e
Add configuration, documentation, code of conduct, contributing guide, license, and README files. Set up .gitignore, coverage config, GitHub issue templates, pull request template, and initial source code, scripts, and tests for DeepLX optimized for Cloudflare Workers.
263 lines
5.9 KiB
Markdown
263 lines
5.9 KiB
Markdown
# Contributing to DeepLX
|
|
|
|
Thank you for your interest in contributing to DeepLX! This document provides guidelines and information for contributors.
|
|
|
|
## Code of Conduct
|
|
|
|
This repository and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
|
|
|
|
## Getting Started
|
|
|
|
1. Fork the repository on GitHub
|
|
2. Clone your fork locally
|
|
3. Set up the development environment
|
|
4. Create a branch for your changes
|
|
5. Make your changes
|
|
6. Test your changes
|
|
7. Submit a pull request
|
|
|
|
## Development Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js >= 18.0.0
|
|
- npm or yarn
|
|
- Cloudflare Wrangler CLI
|
|
|
|
### Installation
|
|
|
|
1. Clone your fork:
|
|
|
|
```bash
|
|
git clone https://github.com/YOUR_USERNAME/DeepLX.git
|
|
cd DeepLX
|
|
```
|
|
|
|
2. Install dependencies:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Set up your development environment:
|
|
|
|
```bash
|
|
npm run test:setup
|
|
```
|
|
|
|
4. Start the development server:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## Making Changes
|
|
|
|
### Branch Naming Convention
|
|
|
|
- `feature/description` - New features
|
|
- `fix/description` - Bug fixes
|
|
- `docs/description` - Documentation updates
|
|
- `refactor/description` - Code refactoring
|
|
- `test/description` - Test improvements
|
|
|
|
### Commit Message Format
|
|
|
|
Use conventional commits format:
|
|
|
|
```
|
|
type(scope): description
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
Types:
|
|
|
|
- `feat`: A new feature
|
|
- `fix`: A bug fix
|
|
- `docs`: Documentation only changes
|
|
- `style`: Changes that do not affect the meaning of the code
|
|
- `refactor`: A code change that neither fixes a bug nor adds a feature
|
|
- `test`: Adding missing tests or correcting existing tests
|
|
- `chore`: Changes to the build process or auxiliary tools
|
|
|
|
Example:
|
|
|
|
```
|
|
feat(api): add new translation feature
|
|
|
|
Implement new endpoint that accepts multiple text inputs
|
|
for translation to improve performance for bulk operations.
|
|
|
|
Closes #123
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
npm test
|
|
|
|
# Run tests with coverage
|
|
npm run test:coverage
|
|
|
|
# Run specific test types
|
|
npm run test:unit
|
|
npm run test:integration
|
|
npm run test:performance
|
|
|
|
# Run tests in watch mode
|
|
npm run test:watch
|
|
```
|
|
|
|
### Writing Tests
|
|
|
|
- Write unit tests for all new functions and classes
|
|
- Add integration tests for API endpoints
|
|
- Include performance tests for critical paths
|
|
- Ensure tests are deterministic and isolated
|
|
- Use descriptive test names and organize with `describe` blocks
|
|
|
|
### Test Requirements
|
|
|
|
- All tests must pass
|
|
- Code coverage should not decrease
|
|
- Integration tests should verify real-world scenarios
|
|
- Performance tests should validate response times
|
|
|
|
## Submitting Changes
|
|
|
|
### Before Submitting
|
|
|
|
1. Ensure all tests pass: `npm test`
|
|
2. Check code style: `npm run lint`
|
|
3. Update documentation if needed
|
|
4. Add tests for new functionality
|
|
5. Update CHANGELOG.md if applicable
|
|
|
|
### Pull Request Process
|
|
|
|
1. Create a pull request from your feature branch
|
|
2. Fill out the PR template completely
|
|
3. Ensure the PR passes all CI checks
|
|
4. Request review from maintainers
|
|
5. Address any feedback promptly
|
|
6. Keep the PR updated with the main branch
|
|
|
|
### PR Requirements
|
|
|
|
- Clear description of changes
|
|
- Reference related issues
|
|
- Include screenshots for UI changes
|
|
- Add performance impact notes if applicable
|
|
- Update documentation as needed
|
|
|
|
## Coding Standards
|
|
|
|
### TypeScript Guidelines
|
|
|
|
- Use strict TypeScript configuration
|
|
- Define explicit types for function parameters and returns
|
|
- Avoid `any` type unless absolutely necessary
|
|
- Use meaningful variable and function names
|
|
- Follow consistent naming conventions
|
|
|
|
### Code Style
|
|
|
|
- Use 2 spaces for indentation
|
|
- Use single quotes for strings
|
|
- Add trailing commas in multiline structures
|
|
- Keep lines under 100 characters
|
|
- Use meaningful comments for complex logic
|
|
|
|
### File Organization
|
|
|
|
- Keep files focused on a single responsibility
|
|
- Use consistent file naming (kebab-case)
|
|
- Export types and interfaces from dedicated files
|
|
- Group related functionality in modules
|
|
|
|
### Performance Considerations
|
|
|
|
- Optimize for Cloudflare Workers environment
|
|
- Minimize memory allocations
|
|
- Use efficient algorithms and data structures
|
|
- Cache frequently accessed data
|
|
- Monitor and test performance impact
|
|
|
|
## Security
|
|
|
|
### Security Guidelines
|
|
|
|
- Never commit sensitive information
|
|
- Use environment variables for configuration
|
|
- Validate all user inputs
|
|
- Implement proper error handling
|
|
- Follow security best practices for APIs
|
|
|
|
### Reporting Security Issues
|
|
|
|
If you discover a security vulnerability, please follow our [Security Policy](SECURITY.md) instead of creating a public issue.
|
|
|
|
## Documentation
|
|
|
|
### Code Documentation
|
|
|
|
- Add JSDoc comments for public APIs
|
|
- Document complex algorithms and business logic
|
|
- Include usage examples in documentation
|
|
- Keep documentation up to date with code changes
|
|
|
|
### README Updates
|
|
|
|
- Update feature lists for new functionality
|
|
- Add new configuration options
|
|
- Update API documentation
|
|
- Include new examples and use cases
|
|
|
|
## Release Process
|
|
|
|
### Versioning
|
|
|
|
We follow [Semantic Versioning](https://semver.org/):
|
|
|
|
- MAJOR: Breaking changes
|
|
- MINOR: New features (backward compatible)
|
|
- PATCH: Bug fixes (backward compatible)
|
|
|
|
### Changelog
|
|
|
|
- Update CHANGELOG.md for all user-facing changes
|
|
- Group changes by type (Added, Changed, Fixed, Removed)
|
|
- Include migration notes for breaking changes
|
|
- Reference related issues and PRs
|
|
|
|
## Getting Help
|
|
|
|
### Communication Channels
|
|
|
|
- GitHub Issues: Bug reports and feature requests
|
|
- GitHub Discussions: Questions and general discussion
|
|
- Pull Request comments: Code review and implementation discussion
|
|
|
|
### Resources
|
|
|
|
- [repository Documentation](README.md)
|
|
- [API Reference](docs/api.md)
|
|
- [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/)
|
|
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
|
|
|
|
## Recognition
|
|
|
|
Contributors will be recognized in:
|
|
|
|
- CHANGELOG.md for significant contributions
|
|
- README.md contributors section
|
|
- GitHub contributors page
|
|
|
|
Thank you for contributing to DeepLX! 🚀
|