|
1 | 1 | # Contributing |
2 | 2 |
|
3 | | -## Creating issues |
| 3 | +## Find or file an issue to work on |
4 | 4 |
|
5 | | -If you notice a discrepancy between PokeAPI's responses and PokeKotlin's object |
6 | | -models, you should create an issue and I'll fix it as soon as possible. You can |
7 | | -also post questions, feature suggestions, general support issues, or anything |
8 | | -else. |
| 5 | +If you're looking to add a feature or fix a bug and there's no issue filed yet, |
| 6 | +it's good to |
| 7 | +[file an issue](https://github.com/pokeapi/pokekotlin/issues/new/choose) first |
| 8 | +to have a discussion about the change before you start working on it. |
9 | 9 |
|
10 | | -## Submitting changes |
| 10 | +If you're new and looking for things to contribute, see our |
| 11 | +[good first issue](https://github.com/pokeapi/pokekotlin/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) |
| 12 | +label. These issues are usually ready to work on and don't require deep |
| 13 | +knowledge of the library's internals. |
11 | 14 |
|
12 | | -Remember to always work in a separate branch, use descriptive commit messages, |
13 | | -and use pull requests to submit your changes. Always create an issue and mention |
14 | | -you're working on something first. Also, make sure that all tests pass. If you |
15 | | -add new fields or types, write the tests to check them against PokeAPI. |
| 15 | +## Development Environment Setup |
| 16 | + |
| 17 | +### Prerequisites |
| 18 | + |
| 19 | +1. **IDE**: [IntelliJ IDEA](https://www.jetbrains.com/idea/) is recommended. |
| 20 | + VSCode and other editors won't work well, as this is a Kotlin project and |
| 21 | + there's not yet a stable LSP for Kotlin. |
| 22 | +2. **Node.js**: Required for running the test server. Instructions can be found |
| 23 | + at [nodejs.org](https://nodejs.org/en/download). |
| 24 | +3. **Just** (optional): A command runner that simplifies running common tasks. |
| 25 | + Installation instructions can be found at |
| 26 | + [just.systems](https://just.systems/man/en/). |
| 27 | + |
| 28 | +### Cloning the Repository |
| 29 | + |
| 30 | +This repository uses a Git submodule for test data. When cloning, make sure to |
| 31 | +include the `--recurse-submodules` flag: |
| 32 | + |
| 33 | +```bash |
| 34 | +git clone --recurse-submodules 'https://github.com/PokeAPI/pokekotlin.git' |
| 35 | +``` |
| 36 | + |
| 37 | +If you've already cloned the repository without submodules, you can initialize |
| 38 | +them with: |
| 39 | + |
| 40 | +```bash |
| 41 | +git submodule update --init --recursive |
| 42 | +``` |
| 43 | + |
| 44 | +### IDE Setup |
| 45 | + |
| 46 | +1. Open the project in IntelliJ IDEA or similar IDE. |
| 47 | +2. Make sure you have the Kotlin Multiplatform plugin installed. This should be |
| 48 | + included by default in recent versions of IntelliJ IDEA and Android Studio. |
| 49 | +3. For more information on setting up Kotlin Multiplatform, refer to the |
| 50 | + [official Kotlin Multiplatform documentation](https://kotlinlang.org/docs/multiplatform-get-started.html). |
| 51 | + |
| 52 | +## Running Tests |
| 53 | + |
| 54 | +Most tests in this project rely on a local server that serves the PokeAPI data |
| 55 | +from static files. The server needs to be running before executing the tests. |
| 56 | + |
| 57 | +### Starting the Test Server |
| 58 | + |
| 59 | +You can start the test server using the provided script: |
| 60 | + |
| 61 | +```bash |
| 62 | +./scripts/test-server |
| 63 | +``` |
| 64 | + |
| 65 | +Or if you have Just installed, you can use: |
| 66 | + |
| 67 | +```bash |
| 68 | +just test-server |
| 69 | +``` |
| 70 | + |
| 71 | +### Running Tests |
| 72 | + |
| 73 | +The project includes tests for various platforms. You can run them using Gradle |
| 74 | +directly or through the Just commands. For details on available commands, see |
| 75 | +the [`justfile`](./justfile) in the project root or run: |
| 76 | + |
| 77 | +```bash |
| 78 | +just |
| 79 | +``` |
| 80 | + |
| 81 | +## Code Formatting |
| 82 | + |
| 83 | +The project uses Spotless for code formatting. You can apply the formatting |
| 84 | +rules with: |
| 85 | + |
| 86 | +```bash |
| 87 | +just format |
| 88 | +``` |
| 89 | + |
| 90 | +Or using Gradle directly: |
| 91 | + |
| 92 | +```bash |
| 93 | +./gradlew spotlessApply |
| 94 | +``` |
| 95 | + |
| 96 | +If you'd prefer to apply automatically on commit, opt in to the pre-commit hook |
| 97 | +with: |
| 98 | + |
| 99 | +```bash |
| 100 | +./gradlew installGitHooks |
| 101 | +``` |
0 commit comments