After another month of solely maintenance, its perhaps worth expanding on what exactly typical “maintenance” entails for the pkmn project. Maintenance broadly falls into two buckets:
- fielding questions and resolving issues/PRs that get opened against the project.
- keeping up-to-date with changes to dependencies/platforms to ensure the code doesn’t rot.
The latter bucket can also be expanded to include staying up-to-date with an “upstream” source-of-truth – in many cases the Pokémon Showdown project or the projects upstream of Pokémon Showdown. In an ideal world, maintenance would only be required due to Nintendo (releasing new games, DLC expansions, individual Pokémon or events or formats) and Smogon (implementing tiering/format changes), though sadly given how many of the pkmn projects depend on Pokémon Showdown, refactors and other low-level changes to smogon/pokemon-showdown cause churn.
Perhaps more frustrating than Pokémon Showdown changes are JavaScript ecosystem (ESLint, TypeScript, React, Vitest, Node/NPM) or Zig changes – both introduce breaking changes on a regular basis that often require rather large workarounds or rewrites to support. Why care? Why ensure that the pkmn projects are always on the bleeding edge of all of these tools as opposed to only updating semi-regularly? 2024-06 goes into more detail here, but the main reason harkens back to the basic principle of the @pkmn organization around attempting to maximize general use – a new user that downloads one of the pkmn projects and attempts to get it running is likely going to want to be able to use somewhat modern versions of tooling and dependencies. A pkmn project requiring version N-10 of a compiler or library while the user would prefer to be using version N or maybe N-1 is a poor user experience.
The pkmn/ps packages are the most complicated to update, and also have a somewhat nuanced release schedule. The idea is to release regularly so that the latest Pokémon and formats are available but to avoid periods of instability when the Pokémon Showdown developers are iterating on large untested changes. This requires following every PR, monitoring reporting bugs, and reading through every commit, occasionally intervening behind-the-scenes to steer developers away from pitfalls and to hopefully mitigate the amount of churn required to stay in sync with the project. Releases are usually cut after notable changes like tiering shifts (e.g, an OverUsed ban, or a new Pokémon being added via DLC) and this naturally means there is always a release at the start of the month after the usage-based tiering updates get made.
Actually updating the pkmn/ps project centers around the incredibly hacky import script which attempts to minimize the amount of manual intervention required (though pretty much every import requires some form of manual work due to the amount pkmn has deviated from upstream). Upstream refactors are particularly punishing due to the fragile nature of the import process, and understanding of how the packages in the repository are dependent on each other and how the rest of the pkmn projects in turn depend on these packages is necessary to successfully keep things in sync.
The other pkmn projects are somewhat simpler to maintain:
- pkmn/randbats: Mostly automated, though new formats or overhauls of how Pokémon Showdown’s random battles work requires manual intervention.
- pkmn/eslint-config: Simple dependency bump at the start of every month.
- pkmn/ai: Google Scholar alerts are set up to detect any new papers related to Pokémon to add to Projects, and new non-Pokémon papers which are relevant get added to Research.
- pkmn/smogon: The data portion is mostly automated, though new monthly format names need to be added manually and test cases occasionally break and need to be updated if Smogon analyses change. The
smogonand@pkmn/smogonpackages get published monthly with their dependencies updated. - pkmn/stats: Updated monthly with the latest pkmn packages, also needs to get updated to reflect changes made to smogon/usage-stats or when Pokémon Showdown’s protocol changes.
- pkmn/engine: Built nightly with the latest Zig compiler which ends up breaking something roughly once every two weeks. When relevant changes to Pokémon Showdown get made the version of
@pkmn/simthe engine pins for testing gets bumped and all of the offsets in the unit tests need to be updated as they (sadly) depend on the exact line numbers of Pokémon Showdown’s code. Occasionally, integration or fuzz tests which get run continuously detect bugs which need to be addressed.
While there is a non-trivial amount of maintenance to stay on top of, the process has been streamlined over time such that the workload is sustainable even during periods of reduced developer bandwidth.
— pre