Skip to content

chore: mark Bukkit commands as obsolete - #14281

Merged
kennytv merged 3 commits into
PaperMC:mainfrom
Strokkur424:chore/obsolete-bukkit-commands
Sep 26, 2026
Merged

kennytv merged 3 commits into
PaperMC:mainfrom
Strokkur424:chore/obsolete-bukkit-commands

Conversation

@Strokkur424

Copy link
Copy Markdown
Member

This PR is an alternative of #14227, whose goal is the complete deprecation of Bukkit commands.

Part of the backlash on that PR, partly also by maintainers, was that deprecation is a fairly strong thing to do out of the blue, and they should be marked obsolete first. Whilst I believe deprecation to be perfectly fine, I've decided to open a second PR to make it as obsolete.

I will keep the deprecation PR open, so that it may be considered in the future (maybe 26.4?), with this PR serving as a transition layer.

@Strokkur424
Strokkur424 requested a review from a team as a code owner September 19, 2026 20:28
@github-project-automation github-project-automation Bot moved this to Awaiting review in Paper PR Queue Sep 19, 2026
@DerEchtePilz

Copy link
Copy Markdown
Contributor

I did not see the previous PR so I am just gonna leave my opinion here.

In my opinion, ApiStatus.Obsolete does nothing. If you asked me I wouldn't be able to tell you if any API element already has that annotation. The only time it does something is when you're actively looking for JavaDocs because then, obviously, you'll see the annotation.

I feel like users who already use those classes and methods are not gonna see those annotations and a later deprecation would, to them, appear to be just as out of the blue as it would be now.

I don't think these classes are gonna be removed any time soon anyway, but if you want to push users towards new API I think an actual deprecation would do much more than an obsoletion.

@Doc94 Doc94 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its a good start, i know people can ignore Obsolete but that already happen with Experimental or even Deprecate (see the damage modifier enum...)
So not hurt mark obsolete in favor of more updated solutions

@papermc-projects papermc-projects Bot moved this from Awaiting review to Delayed approval in Paper PR Queue Sep 19, 2026
@Toffikk

Toffikk commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

While i do think this is laying a good foundation for a future deprecation of these methods, i do not believe this is enough. as @DerEchtePilz correctly pointed out, Obsolete is something that developers will not see unless they're actively looking at javadocs and even then they can miss them. In my opinion, adding a mention about a possible future deprecation and the current marking of these methods as obsolete should be included in something like a 26.3 update post (and the corresponding discord announcement) which will reach more people and more than likely more devs than if it was just a javadoc thing.

@Malfrador

Malfrador commented Sep 24, 2026 •

Copy link
Copy Markdown
Member

I like this a lot more. Bukkit commands are such an integral part of the API that I believe immediate deprecation is too unpredictable and sudden. Unless you regularily follow conversation in the #paper-dev channel or similar places, you likely be entirely unaware that the use of this API is discouraged.
A deprecation would be very out of the blue and further train people to just ignore the many deprecations the API already has, as is already the case.

IMO the order should be:

  1. Mark as obsolete and note alternatives in the JD
  2. Add to https://docs.papermc.io/paper/dev/roadmap/ and add some explanation. This is as big of a change as the ItemStack constructor, it deserves a roadmap mention. We can also easily link to that on the Paper Discord.
  3. Deprecate them the next time maintaining the API would require actual work, e.g. if Mojang changes the command system. Similar to how the Conversation API got deprecated once an update made maintaining it effortful.
  4. As this will be with a major update, we can also easily mention it in the blog post for that update, which a lot of people usually read.

Also ideally #11378, #11891 and #13163 would be fixed before a deprecation.

@kennytv kennytv left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

command aliases aren't really obsolete

@Strokkur424

Copy link
Copy Markdown
Member Author

I've gone ahead and fixed the wrong Javadoc tag and de-obsoleted the command aliases methods from Bukkit and Server. I am guessing you were referencing those, and not the FormattedCommandAlias/MultipleCommandAlias classes, which are part of the Bukkit command system.

@kennytv
kennytv merged commit d289ae1 into PaperMC:main Sep 26, 2026
5 checks passed
@Strokkur424
Strokkur424 deleted the chore/obsolete-bukkit-commands branch September 26, 2026 12:44
granny added a commit to PurpurMC/Purpur that referenced this pull request Sep 27, 2026
Upstream has released updates that appear to apply and compile correctly

Paper Changes:
PaperMC/Paper@a15fed9c Update Gradle to 9.8 and paperweight to beta.24
PaperMC/Paper@08ca088b Count skipped inbound packets for rate limiting PaperMC/Paper#14305
PaperMC/Paper@d289ae1d Mark Bukkit commands as obsolete PaperMC/Paper#14281
PaperMC/Paper@a0919613 Add back mob peaceful despawn override
PaperMC/Paper@f6862603 Skip styledLines in ItemLore hashcode and equals
PaperMC/Paper@b23b7258 Pass on to Vanilla fixers if needed
PaperMC/Paper@640efeea Make CraftWorld#isChunkGenerated use BLOCKING priority
PaperMC/Paper@5cbb5d6f Update leafpile to 1.2.4 PaperMC/Paper#14310
PaperMC/Paper@d3ee2cfc Avoid entity nbt load logic when loading in full entity chunk
PaperMC/Paper@f4eb9c2e Add chunkScanner implementation to ChunkMap
PaperMC/Paper@8c95c89a Avoid default HIGHER priority for getChunkFutureMainThread
PaperMC/Paper@0fdc0885 Rebase fixups
IYeaSakura added a commit to IYeaSakura/PaperMC-Dev-Skills that referenced this pull request Sep 28, 2026
…kit commands

- Paper 26.2 stable 127 -> 129; 26.3 alpha 32 -> 133; Purpur 26.3 2639 -> 2642; Folia still 26.2 build 7 beta

- Document the 26.3 obsolescence of the Bukkit command system (PaperMC/Paper#14281) with both documented replacements: BasicCommand + registerCommand, and Brigadier via LifecycleEvents.COMMANDS

- Update paperweight-userdev to 2.0.0-beta.24

- Record that the 26.3 Javadoc lags the builds (reported build 49 while builds were at 133)

- Sync SKILL.md, references, both READMEs and the blog draft with the new snapshot
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Merged

Development

Successfully merging this pull request may close these issues.

6 participants