From 1ebcf899141f6e975f1c68eb88827ff5432e379f Mon Sep 17 00:00:00 2001 From: canermastan Date: Fri, 23 May 2025 14:42:46 +0300 Subject: [PATCH] chore: Add comprehensive contributor setup - Issue templates (bug, feature, question) - Contributing guide with standards - README updates with community links - Makes contributing easy for all skill levels --- .github/ISSUE_TEMPLATE/bug_report.yml | 58 +++++ .github/ISSUE_TEMPLATE/feature_request.yml | 64 +++++ .github/ISSUE_TEMPLATE/question.yml | 32 +++ CONTRIBUTING.md | 194 +++++++++++++++ README.md | 42 ++-- SUGGESTED_ISSUES.md | 276 +++++++++++++++++++++ 6 files changed, 651 insertions(+), 15 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 CONTRIBUTING.md create mode 100644 SUGGESTED_ISSUES.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..4009e82 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,58 @@ +name: ๐Ÿ› Bug Report +description: Found a bug? Let us know! +title: "[BUG] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for helping make Jazzy Framework better! ๐Ÿ™ + + - type: input + id: version + attributes: + label: Framework Version + description: Which version are you using? + placeholder: e.g., 0.2.0 + validations: + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Tell us what went wrong + placeholder: Describe the bug in a few sentences... + validations: + required: true + + - type: textarea + id: steps + attributes: + label: How can we reproduce it? + description: Simple steps to reproduce the bug + placeholder: | + 1. Create a controller with... + 2. Make a request to... + 3. See error... + validations: + required: true + + - type: textarea + id: code + attributes: + label: Code example (optional) + description: Share a small code snippet if helpful + render: java + placeholder: | + @Component + public class MyController { + // Your code here + } + + - type: textarea + id: error + attributes: + label: Error message (optional) + description: Copy/paste any error messages + render: shell \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..a61fa5f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,64 @@ +name: ๐Ÿ’ก Feature Request +description: Got an idea? Share it with us! +title: "[FEATURE] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for the suggestion! We love new ideas ๐Ÿ’ก + + - type: dropdown + id: category + attributes: + label: What area is this about? + options: + - Core Framework + - Dependency Injection + - HTTP/Routing + - Validation + - Documentation + - Developer Experience + - Other + validations: + required: true + + - type: textarea + id: idea + attributes: + label: What's your idea? + description: Describe the feature you'd like to see + placeholder: I think it would be great if Jazzy could... + validations: + required: true + + - type: textarea + id: why + attributes: + label: Why would this be useful? + description: How would this help you or other developers? + placeholder: This would solve the problem of... + validations: + required: true + + - type: textarea + id: example + attributes: + label: Code example (optional) + description: Show how you imagine this feature working + render: java + placeholder: | + // Example of how this might work + @NewAnnotation + public class ExampleController { + // Your example here + } + + - type: checkboxes + id: help + attributes: + label: Can you help? (optional) + options: + - label: I'd like to implement this myself + - label: I can help with testing + - label: I can help with documentation \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..9eaad2e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,32 @@ +name: โ“ Question +description: Need help with something? +title: "[QUESTION] " +labels: ["question"] +body: + - type: markdown + attributes: + value: | + Need help? We're here for you! ๐Ÿค + + - type: textarea + id: question + attributes: + label: What do you need help with? + description: Ask your question + placeholder: How do I...? / Why does...? / Can Jazzy Framework...? + validations: + required: true + + - type: textarea + id: tried + attributes: + label: What have you tried? (optional) + description: Let us know what you've already attempted + placeholder: I tried following the documentation but... + + - type: textarea + id: code + attributes: + label: Code example (optional) + description: Share your code if relevant + render: java \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..88a2e5a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,194 @@ +# Contributing to Jazzy Framework + +Thank you for your interest in contributing to Jazzy Framework! ๐ŸŽ‰ + +## Ways to Contribute + +There are many ways you can contribute to Jazzy Framework: + +- ๐Ÿ› **Report bugs** using our bug report template +- ๐Ÿ’ก **Suggest features** using our feature request template +- ๐Ÿ“ **Improve documentation** - fix typos, add examples, clarify explanations +- ๐Ÿงช **Write tests** - help us reach 100% test coverage +- ๐Ÿ”ง **Fix bugs** - tackle issues labeled with `good first issue` +- โญ **Add new features** - implement requested features +- ๐Ÿ“š **Create examples** - build sample applications showcasing framework features + +## Getting Started + +### 1. Fork and Clone +```bash +git clone https://github.com/YOUR_USERNAME/jazzy-framework.git +cd jazzy-framework +``` + +### 2. Build the Project +```bash +# Install dependencies and run tests +mvn clean install + +# Run tests only +mvn test + +# Run example application +mvn exec:java -Dexec.mainClass="examples.basic.App" +``` + +### 3. Make Your Changes + +#### For Bug Fixes: +1. Create a branch: `git checkout -b fix/issue-123-description` +2. Write tests that reproduce the bug +3. Fix the bug +4. Ensure all tests pass +5. Update documentation if needed + +#### For New Features: +1. Create a branch: `git checkout -b feature/feature-name` +2. Write tests for the new feature +3. Implement the feature +4. Add documentation and examples +5. Ensure all tests pass + +#### For Documentation: +1. Create a branch: `git checkout -b docs/description` +2. Update relevant `.md` files or javadocs +3. Test documentation builds (if applicable) + +### 4. Commit Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/): + +```bash +# Examples: +git commit -m "feat: add middleware support to router" +git commit -m "fix: resolve null pointer in DI container" +git commit -m "docs: add examples for @Named annotation" +git commit -m "test: add integration tests for validation" +git commit -m "chore: update dependencies" +``` + +**Types:** +- `feat:` - New features +- `fix:` - Bug fixes +- `docs:` - Documentation changes +- `test:` - Adding/updating tests +- `chore:` - Maintenance tasks +- `refactor:` - Code refactoring +- `perf:` - Performance improvements + +### 5. Pull Request Process + +1. **Update your branch** with latest main: + ```bash + git checkout main + git pull origin main + git checkout your-branch + git rebase main + ``` + +2. **Run the full test suite**: + ```bash + mvn clean test + ``` + +3. **Create Pull Request** with: + - Clear title describing the change + - Detailed description of what was changed and why + - Link to related issues + - Screenshots/examples if applicable + +## Code Standards + +### Java Code Style +- **Indentation**: 4 spaces (no tabs) +- **Line Length**: Maximum 120 characters +- **Naming**: + - Classes: `PascalCase` + - Methods/Variables: `camelCase` + - Constants: `UPPER_SNAKE_CASE` +- **Javadoc**: Required for all public methods and classes + +### Testing +- **Test Coverage**: Aim for >90% coverage for new code +- **Test Naming**: Use descriptive names that explain what is being tested +- **Test Structure**: Follow Arrange-Act-Assert pattern + +Example: +```java +@Test +public void shouldInjectDependencyWhenComponentHasConstructorParameter() { + // Arrange + DIContainer container = new DIContainer(); + container.register(UserRepository.class); + + // Act + UserService service = container.getBean(UserService.class); + + // Assert + assertThat(service.getRepository()).isNotNull(); +} +``` + +## Good First Issues + +Looking for a good first contribution? Check out issues labeled: + +- ๐ŸŸข `good first issue` - Perfect for beginners +- ๐Ÿ“š `documentation` - Documentation improvements +- ๐Ÿงช `tests` - Writing or improving tests +- ๐Ÿ› `bug` - Bug fixes with clear reproduction steps + +## Development Setup + +### Prerequisites +- Java 11 or higher +- Maven 3.6+ +- Git + +### Running Tests +```bash +# Run all tests +mvn test + +# Run specific test class +mvn test -Dtest=DIContainerTest + +# Run tests with coverage (if configured) +mvn test +``` + +### Building Documentation +```bash +cd docs-site +npm install +npm run build +npm run serve +``` + +## Community Guidelines + +### Be Respectful +- Use welcoming and inclusive language +- Be respectful of differing viewpoints and experiences +- Accept constructive criticism gracefully +- Focus on what is best for the community + +### Communication +- **Issues**: Use issue templates for bug reports and feature requests +- **Pull Requests**: Provide clear descriptions and context + +## Recognition + +Contributors are recognized in our: +- ๐Ÿ† GitHub contributors graph +- ๐Ÿ“š Release notes for significant contributions + +## Questions? + +- ๐Ÿ’ฌ **General Questions**: Use [GitHub Discussions](https://github.com/canermastan/jazzy-framework/discussions) for community help +- ๐Ÿ› **Bug Reports**: Use our [bug report template](https://github.com/canermastan/jazzy-framework/issues/new?template=bug_report.yml) +- ๐Ÿ’ก **Feature Ideas**: Use our [feature request template](https://github.com/canermastan/jazzy-framework/issues/new?template=feature_request.yml) +- โ“ **Questions**: Use our [question template](https://github.com/canermastan/jazzy-framework/issues/new?template=question.yml) + +Thank you for contributing to Jazzy Framework! ๐Ÿš€ \ No newline at end of file diff --git a/README.md b/README.md index 8e46a58..12d2b84 100644 --- a/README.md +++ b/README.md @@ -258,25 +258,37 @@ You can gradually migrate - mix DI and manual instantiation in the same applicat We believe that open source thrives with community involvement, and we appreciate all types of contributions, whether you're fixing a typo, improving documentation, adding a new feature, or reporting a bug. -### Getting Started +### ๐Ÿ“– Complete Contributing Guide -1. Fork the project -2. Clone your fork (`git clone https://github.com/canermastan/jazzy-framework.git`) -3. Create a feature branch (`git checkout -b feature/amazing-feature`) -4. Make your changes (don't forget to add tests if applicable) -5. Run tests to make sure everything works (`mvn test`) -6. Commit your changes (`git commit -m 'Add some amazing feature'`) -7. Push to the branch (`git push origin feature/amazing-feature`) -8. Open a Pull Request +For detailed contribution guidelines, development setup, and code standards, see our **[Contributing Guide](CONTRIBUTING.md)**. -### Pull Request Guidelines +### ๐Ÿš€ Quick Start for Contributors -- Keep your changes focused on a single issue -- Make sure all tests pass -- Update documentation if needed -- Follow existing code style +1. **Read our [Contributing Guide](CONTRIBUTING.md)** for detailed instructions +2. **Fork the project** and clone your fork +3. **Check out [good first issues](https://github.com/canermastan/jazzy-framework/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** for beginner-friendly tasks +4. **Create a feature branch** (`git checkout -b feature/amazing-feature`) +5. **Make your changes** and add tests if applicable +6. **Run tests** to make sure everything works (`mvn test`) +7. **Commit your changes** following [Conventional Commits](https://www.conventionalcommits.org/) +8. **Push to your branch** and open a Pull Request -No contribution is too small, and we're happy to help newcomers get started! +### ๐Ÿค Community & Support + +- ๐Ÿ’ฌ **[GitHub Discussions](https://github.com/canermastan/jazzy-framework/discussions)** - Community help and general questions +- ๐Ÿ› **[Report Issues](https://github.com/canermastan/jazzy-framework/issues/new/choose)** - Bug reports and feature requests +- ๐Ÿ“š **[Documentation](https://canermastan.github.io/jazzy-framework/)** - Complete framework documentation +- ๐ŸŽฏ **[Good First Issues](https://github.com/canermastan/jazzy-framework/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** - Perfect for newcomers + +### ๐Ÿท๏ธ Issue Templates + +We have beginner-friendly issue templates to help you contribute: + +- ๐Ÿ› **Bug Report** - Found something broken? +- ๐Ÿ’ก **Feature Request** - Have an idea for improvement? +- โ“ **Question** - Need help with something? + +No contribution is too small, and we're happy to help newcomers get started! ๐Ÿš€ ## License diff --git a/SUGGESTED_ISSUES.md b/SUGGESTED_ISSUES.md new file mode 100644 index 0000000..e038d8a --- /dev/null +++ b/SUGGESTED_ISSUES.md @@ -0,0 +1,276 @@ +# Suggested Issues for Contributors + +This file contains suggested issues to create for encouraging contributions to Jazzy Framework. Copy these to GitHub Issues manually. + +## ๐ŸŸข Good First Issues (Beginner Friendly) + +### 1. ๐Ÿ“ Add more examples to README +**Title**: Add more code examples to README.md +**Labels**: `good first issue`, `documentation` +**Description**: +The README could benefit from more practical examples showing different aspects of the framework. Add examples for: +- Basic validation usage +- Path parameters extraction +- JSON response building +- Error handling + +**Acceptance Criteria**: +- [ ] Add 2-3 more code examples to README.md +- [ ] Examples should be runnable +- [ ] Include comments explaining key concepts + +--- + +### 2. ๐Ÿงช Increase test coverage for validation module +**Title**: Add tests for edge cases in validation system +**Labels**: `good first issue`, `tests` +**Description**: +The validation module needs more test coverage for edge cases. Current coverage could be improved by testing: +- Empty string validation +- Null value handling +- Custom error messages +- Edge cases for minLength/maxLength + +**Acceptance Criteria**: +- [ ] Add at least 5 new test cases +- [ ] Test coverage increase by 10%+ +- [ ] All tests pass + +--- + +### 3. ๐Ÿ“š Add Javadoc comments to public methods +**Title**: Add missing Javadoc comments to core classes +**Labels**: `good first issue`, `documentation` +**Description**: +Several public methods in core classes are missing Javadoc comments. Add comprehensive documentation for: +- `Request.java` methods +- `Response.java` methods +- `Router.java` methods + +**Example**: +```java +/** + * Extracts a path parameter from the request URL. + * + * @param key the parameter name to extract + * @return the parameter value, or null if not found + * @since 0.2.0 + */ +public String getPathParam(String key) { + // existing code +} +``` + +--- + +### 4. ๐Ÿ”ง Add more validation rules +**Title**: Implement additional validation rules +**Labels**: `good first issue`, `enhancement` +**Description**: +Add new validation rules to make the validation system more comprehensive: +- `numeric()` - validates that field contains only numbers +- `alpha()` - validates that field contains only letters +- `alphanumeric()` - validates letters and numbers only +- `minValue(int min)` / `maxValue(int max)` - for numeric range validation + +**Acceptance Criteria**: +- [ ] Implement the 4 new validation rules +- [ ] Add comprehensive tests for each rule +- [ ] Update documentation with examples + +--- + +## ๐ŸŸก Intermediate Issues + +### 5. ๐Ÿš€ Implement middleware system +**Title**: Add middleware support to routing system +**Labels**: `enhancement`, `help wanted` +**Description**: +Implement a middleware system that allows intercepting requests before they reach controllers. Similar to Express.js middleware. + +**Requirements**: +- Before and after middleware support +- Multiple middleware chaining +- Request/response modification capability +- Error handling in middleware + +**Example Usage**: +```java +router.middleware(new LoggingMiddleware()); +router.middleware(new AuthenticationMiddleware()); +router.GET("/protected", "getSecretData", SecretController.class); +``` + +--- + +### 6. ๐Ÿ“Š Add request/response logging middleware +**Title**: Create built-in logging middleware for requests +**Labels**: `enhancement`, `good for beginners` +**Description**: +Create a logging middleware that automatically logs: +- Request method, URL, headers +- Response status code, execution time +- Request/response body (configurable) + +Should integrate with Java logging frameworks (SLF4J). + +--- + +### 7. ๐Ÿ”’ Implement CORS support +**Title**: Add CORS (Cross-Origin Resource Sharing) support +**Labels**: `enhancement`, `security` +**Description**: +Add built-in CORS support to handle cross-origin requests: +- Configurable allowed origins +- Support for preflight requests +- Configurable allowed methods and headers + +--- + +### 8. โšก Add async request handling +**Title**: Implement asynchronous request handling +**Labels**: `enhancement`, `performance` +**Description**: +Add support for async request processing using CompletableFuture: +- Controllers can return CompletableFuture +- Non-blocking I/O for better performance +- Proper error handling for async operations + +--- + +## ๐Ÿ”ด Advanced Issues + +### 9. ๐Ÿ—„๏ธ Database integration layer +**Title**: Implement database integration with connection pooling +**Labels**: `enhancement`, `database`, `advanced` +**Description**: +Create a database integration layer: +- JDBC connection pooling (HikariCP) +- Simple query builder +- Transaction management +- Integration with DI system + +**Features**: +- `@Repository` annotation with automatic connection injection +- Simple ORM-like functionality +- Migration system + +--- + +### 10. ๐Ÿ” Authentication and authorization system +**Title**: Implement JWT-based authentication system +**Labels**: `enhancement`, `security`, `advanced` +**Description**: +Add comprehensive auth system: +- JWT token generation and validation +- `@Secured` annotation for protecting endpoints +- Role-based access control +- Password hashing utilities + +--- + +### 11. ๐Ÿ“ฑ WebSocket support +**Title**: Add WebSocket support for real-time communication +**Labels**: `enhancement`, `advanced` +**Description**: +Implement WebSocket support: +- WebSocket endpoint annotations +- Message broadcasting +- Connection management +- Integration with DI system + +--- + +### 12. ๐Ÿ—๏ธ CLI code generation tool +**Title**: Create CLI tool for scaffolding Jazzy applications +**Labels**: `enhancement`, `tooling`, `advanced` +**Description**: +Build a command-line tool similar to Spring Boot CLI: +- Generate new projects +- Create controllers, services, repositories +- Add dependencies +- Generate Docker configurations + +--- + +## ๐Ÿงฉ Fun/Creative Issues + +### 13. ๐ŸŽจ Create framework logo and branding +**Title**: Design official Jazzy Framework logo +**Labels**: `design`, `branding`, `help wanted` +**Description**: +Design a professional logo for Jazzy Framework: +- SVG format for scalability +- Multiple variations (light/dark theme) +- Favicon version +- Update README with logo + +--- + +### 14. ๐Ÿ“บ Create video tutorials +**Title**: Record framework tutorial videos +**Labels**: `documentation`, `video`, `help wanted` +**Description**: +Create educational video content: +- "Getting Started with Jazzy Framework" (5-10 min) +- "Dependency Injection Deep Dive" (10-15 min) +- "Building a Complete REST API" (20-30 min) + +--- + +### 15. ๐Ÿ† Add benchmarking suite +**Title**: Create performance benchmarking suite +**Labels**: `performance`, `testing`, `advanced` +**Description**: +Build comprehensive benchmarks: +- Request throughput testing +- Memory usage profiling +- Comparison with other frameworks +- Automated benchmark reports + +--- + +## โ“ Research/Discussion Issues + +### 16. ๐Ÿ’ญ Research: Plugin system architecture +**Title**: Research and design plugin system for Jazzy Framework +**Labels**: `research`, `enhancement`, `discussion` +**Description**: +Research how to implement a plugin system: +- Plugin discovery mechanism +- Plugin lifecycle management +- API for plugin development +- Security considerations + +Create a design document with recommendations. + +--- + +### 17. ๐Ÿ” Performance analysis and optimization opportunities +**Title**: Analyze framework performance and identify optimization areas +**Labels**: `performance`, `research` +**Description**: +Conduct thorough performance analysis: +- Profile memory usage +- Identify bottlenecks +- Compare with similar frameworks +- Create optimization roadmap + +--- + +## How to Use This List + +1. **Copy issues to GitHub**: Create these as actual GitHub issues +2. **Add appropriate labels**: Use GitHub labels to categorize +3. **Link related issues**: Reference related issues when applicable +4. **Update regularly**: Add new issues as the project evolves +5. **Celebrate contributions**: Recognize contributors in release notes + +Remember to: +- Be welcoming to new contributors +- Provide clear acceptance criteria +- Offer help and guidance +- Review contributions promptly +- Thank contributors for their time + +Happy contributing! ๐Ÿš€ \ No newline at end of file