|
| 1 | +# Contributing to Kotlin Notion Client |
| 2 | + |
| 3 | +Thank you for your interest in contributing to the Kotlin Notion Client! This document provides guidelines and information for contributors. |
| 4 | + |
| 5 | +## Project Philosophy |
| 6 | + |
| 7 | +This library aims to provide a modern, type-safe, idiomatic Kotlin interface for the Notion API. Contributions should align with these principles: |
| 8 | + |
| 9 | +- **Type Safety First**: Leverage Kotlin's type system to prevent errors |
| 10 | +- **Kotlin Idioms**: Follow Kotlin best practices and conventions |
| 11 | +- **DSL-Style APIs**: Prefer builder patterns for complex objects |
| 12 | +- **Clear Documentation**: Code should be self-documenting with helpful KDoc |
| 13 | +- **Comprehensive Testing**: All features should have thorough test coverage |
| 14 | + |
| 15 | +## Development Context |
| 16 | + |
| 17 | +This project was developed with significant AI assistance (Claude Code). This is disclosed openly in the README. We welcome contributions from all developers, whether human-written, AI-assisted, or collaborative approaches. |
| 18 | + |
| 19 | +## How to Contribute |
| 20 | + |
| 21 | +### Reporting Issues |
| 22 | + |
| 23 | +- **Bug Reports**: Use GitHub Issues with clear reproduction steps |
| 24 | +- **Feature Requests**: Explain the use case and how it aligns with project goals |
| 25 | +- **Documentation Issues**: Point out unclear or incorrect documentation |
| 26 | + |
| 27 | +### Code Contributions |
| 28 | + |
| 29 | +1. **Fork and Clone** |
| 30 | + ```bash |
| 31 | + git fork https://github.com/jsaabel/kotlin-notion-client.git |
| 32 | + git clone https://github.com/YOUR_USERNAME/kotlin-notion-client.git |
| 33 | + cd kotlin-notion-client |
| 34 | + ``` |
| 35 | + |
| 36 | +2. **Create a Branch** |
| 37 | + ```bash |
| 38 | + git checkout -b feature/your-feature-name |
| 39 | + # or |
| 40 | + git checkout -b fix/issue-description |
| 41 | + ``` |
| 42 | + |
| 43 | +3. **Make Changes** |
| 44 | + - Follow existing code style (Kotlinter enforces formatting) |
| 45 | + - Add tests for new functionality |
| 46 | + - Update documentation as needed |
| 47 | + - Keep commits focused and atomic |
| 48 | + |
| 49 | +4. **Test Your Changes** |
| 50 | + ```bash |
| 51 | + # Format code |
| 52 | + ./gradlew formatKotlin |
| 53 | + |
| 54 | + # Run unit tests |
| 55 | + ./gradlew test -Dkotest.tags.include="Unit" |
| 56 | + |
| 57 | + # Build project |
| 58 | + ./gradlew build |
| 59 | + ``` |
| 60 | + |
| 61 | +5. **Commit** |
| 62 | + - Use [Conventional Commits](https://www.conventionalcommits.org/) format |
| 63 | + - Examples: |
| 64 | + - `feat: add support for database templates` |
| 65 | + - `fix: resolve null pointer in rich text parsing` |
| 66 | + - `docs: update examples in pages.md` |
| 67 | + - `test: add unit tests for filter DSL` |
| 68 | + |
| 69 | +6. **Push and Create PR** |
| 70 | + ```bash |
| 71 | + git push origin feature/your-feature-name |
| 72 | + ``` |
| 73 | + Then open a Pull Request on GitHub with: |
| 74 | + - Clear description of changes |
| 75 | + - Link to related issues |
| 76 | + - Test results if applicable |
| 77 | + |
| 78 | +## Development Setup |
| 79 | + |
| 80 | +### Prerequisites |
| 81 | +- JDK 17 or higher |
| 82 | +- Gradle (wrapper included) |
| 83 | +- Git |
| 84 | + |
| 85 | +### Building from Source |
| 86 | +```bash |
| 87 | +./gradlew build |
| 88 | +``` |
| 89 | + |
| 90 | +### Running Tests |
| 91 | +```bash |
| 92 | +# Unit tests only (fast, no API calls) |
| 93 | +./gradlew test -Dkotest.tags.include="Unit" |
| 94 | + |
| 95 | +# Integration tests (requires NOTION_API_TOKEN) |
| 96 | +export NOTION_RUN_INTEGRATION_TESTS=true |
| 97 | +export NOTION_API_TOKEN="secret_..." |
| 98 | +export NOTION_TEST_PAGE_ID="page-id" |
| 99 | +./gradlew test --tests "*YourIntegrationTest" |
| 100 | +``` |
| 101 | + |
| 102 | +**Important**: Do not run all integration tests at once - they make many real API calls. |
| 103 | + |
| 104 | +### Code Style |
| 105 | + |
| 106 | +The project uses [Kotlinter](https://github.com/jeremymailen/kotlinter-gradle) for code formatting: |
| 107 | + |
| 108 | +```bash |
| 109 | +# Format all code |
| 110 | +./gradlew formatKotlin |
| 111 | + |
| 112 | +# Check formatting |
| 113 | +./gradlew lintKotlin |
| 114 | +``` |
| 115 | + |
| 116 | +Always run `formatKotlin` before committing. |
| 117 | + |
| 118 | +## Testing Guidelines |
| 119 | + |
| 120 | +### Unit Tests |
| 121 | +- Use MockResponseBuilder for HTTP mocking |
| 122 | +- Use TestFixtures for official API sample responses |
| 123 | +- Tag with `@Tags("Unit")` |
| 124 | +- Should run in <1 second |
| 125 | +- Example: |
| 126 | + ```kotlin |
| 127 | + @Tags("Unit") |
| 128 | + class MyFeatureTest : FunSpec({ |
| 129 | + test("should parse official API response") { |
| 130 | + val response = TestFixtures.Pages.retrievePage() |
| 131 | + val page = response.decode<Page>() |
| 132 | + page.id shouldBe "expected-id" |
| 133 | + } |
| 134 | + }) |
| 135 | + ``` |
| 136 | + |
| 137 | +### Integration Tests |
| 138 | +- Tag with `@Tags("Integration", "RequiresApi")` |
| 139 | +- Check for environment variables before running |
| 140 | +- Clean up resources after test |
| 141 | +- Example: |
| 142 | + ```kotlin |
| 143 | + @Tags("Integration", "RequiresApi") |
| 144 | + class MyIntegrationTest : FunSpec({ |
| 145 | + test("should create page via API").config(enabledIf = shouldRunIntegrationTests()) { |
| 146 | + // Test implementation |
| 147 | + } |
| 148 | + }) |
| 149 | + ``` |
| 150 | + |
| 151 | +## Documentation |
| 152 | + |
| 153 | +### Code Documentation |
| 154 | +- Public APIs should have KDoc comments |
| 155 | +- Include `@param`, `@return`, `@throws` as appropriate |
| 156 | +- Provide usage examples in KDoc |
| 157 | + |
| 158 | +### Guides |
| 159 | +- Update relevant docs in `docs/` directory |
| 160 | +- Keep examples accurate and tested |
| 161 | +- Use clear, beginner-friendly language |
| 162 | + |
| 163 | +## What We're Looking For |
| 164 | + |
| 165 | +**High Priority**: |
| 166 | +- Bug fixes with test cases |
| 167 | +- Improved error messages |
| 168 | +- Documentation improvements |
| 169 | +- Real-world usage feedback |
| 170 | +- Performance optimizations |
| 171 | + |
| 172 | +**Medium Priority**: |
| 173 | +- New features aligned with Notion API capabilities |
| 174 | +- Additional test coverage |
| 175 | +- Code quality improvements |
| 176 | + |
| 177 | +**Low Priority**: |
| 178 | +- Major architectural changes (discuss first) |
| 179 | +- Dependencies updates (unless fixing a specific issue) |
| 180 | + |
| 181 | +## Questions? |
| 182 | + |
| 183 | +- Check [CLAUDE.md](CLAUDE.md) for project guidelines |
| 184 | +- Review existing code for patterns |
| 185 | +- Open a discussion issue before major changes |
| 186 | +- Reach out via GitHub Issues for questions |
| 187 | + |
| 188 | +## Code of Conduct |
| 189 | + |
| 190 | +Be respectful, constructive, and collaborative. We're all here to build better software. |
| 191 | + |
| 192 | +## License |
| 193 | + |
| 194 | +By contributing, you agree that your contributions will be licensed under the MIT License. |
| 195 | + |
| 196 | +--- |
| 197 | + |
| 198 | +Thank you for contributing to Kotlin Notion Client! |
0 commit comments