You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+31-18Lines changed: 31 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,18 +1,19 @@
1
1
<!--
2
-
SPDX-FileCopyrightText: 2024-2025 Pagefault Games
2
+
SPDX-FileCopyrightText: 2024-2026 Pagefault Games
3
3
4
4
SPDX-License-Identifier: CC-BY-NC-SA-4.0
5
5
-->
6
6
7
7
# Contributing to PokéRogue
8
8
9
-
Thank you for taking the time to contribute, every little bit helps. This project is entirely open-source and unmonetized - community contributions are what keep it alive!
9
+
Thank you for taking the time to contribute; every little bit helps! This project is entirely open-source and unmonetized - community contributions are what keep it alive!
10
10
11
11
Please make sure you understand everything relevant to your changes from the [Table of Contents](#-table-of-contents), and absolutely *feel free to reach out in the **#pokerogue-dev** channel on [Discord](https://discord.gg/pokerogue)*.
12
12
We are here to help and the better you understand what you're working on, the easier it will be for it to find its way into the game.
13
13
14
-
Note that, as per GitHub's [terms of service](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license), any contributions made to this repository will be licensed under this repository's terms.
15
-
If you use any external code, please make sure to follow its licensing information. Please make use of [SPDX snippets](https://reuse.software/spec-3.3/#in-line-snippet-comments) for the portion of the file that is licensed differently.
14
+
> [!NOTE]
15
+
> As per GitHub's [terms of service](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license), any contributions made to this repository will be licensed under this repository's terms.
16
+
> If you use any external code, please make sure to follow its licensing information. Please make use of [SPDX snippets](https://reuse.software/spec-3.3/#in-line-snippet-comments) for any portion of the file that is licensed differently.
16
17
17
18
18
19
## 📄 Table of Contents
@@ -32,7 +33,6 @@ PokéRogue is built with [TypeScript](https://www.typescriptlang.org/docs/handbo
32
33
33
34
If you have the motivation and experience with TypeScript/JavaScript (or are willing to learn), you can contribute by forking the repository and making pull requests with contributions.
34
35
35
-
36
36
## 💻 Environment Setup
37
37
38
38
### Codespaces/Devcontainer Environment
@@ -51,8 +51,8 @@ This Linux environment comes with all required dependencies needed to start work
> Due to quirks of devcontainer port forwarding, you must use **`pnpm start:podman`** to start a local dev server from within a devcontainer.
55
-
> All other instructions remain the same as local development.
54
+
> Due to quirks of devcontainer port forwarding, **you must use `pnpm start:podman`** to start a local dev server from within a devcontainer.
55
+
> _All other instructions remain the same as local development_.
56
56
57
57
### Podman
58
58
@@ -95,7 +95,7 @@ You are free to comment on any issue so that you may be assigned to it and we ca
95
95
96
96
## 📚 Documentation
97
97
98
-
You can find the auto-generated documentation [here](https://pagefaultgames.github.io/pokerogue/main/index.html).
98
+
You can find the auto-generated API documentation [here](https://pagefaultgames.github.io/pokerogue/beta/index.html). It can be incomplete at times (as many methods lack documentation comments), but it's a great way to get a look at the overall structure of the codebase and find particular methods or classes you may be looking for.
99
99
100
100
Additionally, the [docs folder](./docs) contains a variety of in-depth documents and guides useful for aspiring contributors. \
101
101
Notable topics include:
@@ -105,17 +105,19 @@ Notable topics include:
105
105
-[Enemy AI move selection](./docs/enemy-ai.md)
106
106
-[Running with Podman](./docs/podman.md)
107
107
108
-
Again, if you have unanswered questions please feel free to ask!
108
+
Again, please feel free to ask any questions you may have!
109
109
110
110
## 🧪 Testing Your Changes
111
111
112
-
You've just made a change - how can you check if it works? You have two areas to hit:
112
+
You've just made a change - how can you check if it works? \
113
+
You have two areas to hit:
113
114
114
115
### 1 - Manual Testing
115
116
116
117
> This will likely be your first stop. After making a change, you'll want to spin the game up and make sure everything is as you expect. To do this, you will need a way to manipulate the game to produce the situation you're looking to test.
117
118
118
119
[src/overrides.ts](./src/overrides.ts) contains overrides for most values you'll need to change for testing, controlled through the `overrides` object.
120
+
There are a variety of overrides available, ranging from changing movesets and abilities to modifying battle conditions and forcing specific scenarios.
119
121
For example, here is how you could test a scenario where the player Pokemon has the ability Drought and the enemy Pokemon has the move Water Gun:
Read through `src/overrides.ts` file to find the override that fits your needs - there are a lot of them!
129
-
If the situation you're trying to test can't be created using existing overrides (or with the [Dev Save](#-development-save-file)), reach out in **#pokerogue-dev**.
130
-
You can get help testing your specific changes, and you might have found a new override that needs to be created!
130
+
> [!NOTE]
131
+
> If the situation you're trying to test can't be created using existing overrides (or with the [Dev Save](#-development-save-file)), reach out in **#pokerogue-dev**.
132
+
> You can get help testing your specific changes, and you might have found a new override that needs to be created!
131
133
132
134
### 2 - Automatic Testing
133
135
136
+
<!-- TODO: Consider moving this to a separate document. There's tons more we could (and should) expand on here, like the `test:create` script, all of the test utils/etc, project conventions, etc etc.-->
137
+
134
138
PokéRogue uses [Vitest](https://vitest.dev/) for automated testing.
135
139
Checking out existing tests in the [test](./test/) folder is a great way to understand how the existing system works, as well as familiarizing yourself with the project as a whole.
136
140
@@ -145,11 +149,19 @@ Ensure that new test cases:
145
149
- Do not test multiple separate things in the same test case. If you have made two distinct changes, they should be tested in two separate cases.
146
150
- Cover as many edge cases as possible. A good strategy is to think of edge cases beforehand and create tests for them using `it.todo`. Once the edge case has been handled, you can remove the `todo` marker.
147
151
148
-
<!-- TODO: Decide on and suggest a specific placement heiarchy for test cases involving interactions between different moves/abilities/etc. -->
152
+
> [!CAUTION]
153
+
> Testing UI-related code within the automated test harness is _usually_ a bad idea. \
154
+
> While it can be done, such tests tend to be boilerplate-heavy, hard to maintain and prone to randomly breaking/timing out.
155
+
> If your change is primarily UI-related, it's usually best to test it manually and only use automated tests for the underlying logic (if applicable).
156
+
157
+
<!-- TODO: Decide on and suggest a specific placement hierarchy for test cases involving interactions between different moves/abilities/etc., and enforce said placement if feasible -->
158
+
159
+
> [!NOTE]
160
+
> While Vitest does support both Jest and Chai syntax for assertions, our project exclusively uses Jest-style assertions (`...toBe()`, `...toEqual()`, etc.) for internal consistency. (The Chai variants have been blacklisted via TypeScript declaration merging, ensuring they aren't accidentally used by mistake.)
149
161
150
162
#### Running tests
151
-
To make sure your changes didn't break any existing test cases, run `pnpm test:silent` in your terminal to run the full test suite. \
152
-
You can provide additional arguments to the command to change its behavior or specify which test files to run;
163
+
To make sure your changes didn't break any existing test cases, run `pnpm test:silent <files>` in your terminal to run test files associated with your changes. \
164
+
You can provide additional arguments to the command to alter its behavior;
153
165
a full list of supported arguments can be found on [Vitest's website](https://vitest.dev/guide/cli.html).
154
166
155
167
> [!CAUTION]
@@ -158,10 +170,11 @@ a full list of supported arguments can be found on [Vitest's website](https://vi
158
170
159
171
## 💾 Development Save File
160
172
> Some issues may require you to have unlocks on your save file which go beyond normal overrides.
161
-
> For this reason, the repository contains a [save file](test/test-utils/saves/everything.psrv) with _everything_ unlocked (it may also contain things that are not legitimately obtainable).
173
+
> For this reason, the repository contains a [save file](test/utils/saves/everything.prsv) with _everything_ unlocked (including things not legitimately obtainable, like unreleased variant shinies).
162
174
163
175
1. Start the game up locally and navigate to `Menu -> Manage Data -> Import Data`
164
-
2. Select [everything.prsv](test/test-utils/saves/everything.prsv) (`test/test-utils/saves/everything.prsv`) and confirm.
176
+
2. Select [everything.prsv](test/utils/saves/everything.prsv) (`test/utils/saves/everything.prsv`) and hit "Confirm".
177
+
3. The page will reload with everything unlocked! You can now test your changes with this save file.
0 commit comments