Together-Java
Decouple forum post creation from TransferQuestionCommand into a more accessible space
Motivation
Forum Channels are common on Discord. By having a centralized API to perform forum actions, developers would be more encouraged to make use of forum posting for bot actions. The API could be scaled to include utility which eases the use of forums in code, as well as to help ease migration-based breakage.
This new Forum Posting API will start extremely lightweight & streamlined, but could be used as a foundation for improvement (such as acting as a facade for complex forum-based operations)
Goals
- Allow access to a forum post creation system, which currently lives in
TransferQuestionCommand - Centralize forum posting, allowing for cross-cutting management over forums (JDA API breakage, styling, etc..)
Risks and Assumptions
- Increasing visibility of an API can bloat the API of the code base
- Any changes to a code base could encounter problems if not properly assessed/tested
Alternatives
- Use non-forum based channels for bot posting
- Manually write-out the forum post creation code each time forum post creation needed
Potential Usage
Creating a new post
var forumChannel = ...; // could use channel or channelId (in String form)
var forumTitle = "My First Post";
var messageData = MessageCreateData.fromContent("Hello world!");
ForumPoster.using(jda)
.createPost(forumChannel, forumTitle, messageData)
.setTags(...) // access to ForumPostAction methods
.addFiles(...)
.queue();
Sending a message to a forum thread
var threadChannel = ...; // could use channel or channelId (in String form)
var messageData = MessageCreateData.fromContent("How's it going?");
ForumPoster.using(jda)
.sendPost(threadChannel, messageData)
.addFiles(...) // access to MessageCreateAction methods
.queue();
Usage in TransferQuestionCommand (Low Impact)
From
return questionsForum.createForumPost(forumTitle, forumMessage)
.setTags(ForumTagSnowflake.fromId(tag.getId()))
.map(createdPost -> new ForumPostData(createdPost, originalUser));
To
return ForumPoster.using(jda).createPost(forumTitle, forumMessage)
.setTags(ForumTagSnowflake.fromId(tag.getId()))
.map(createdPost -> new ForumPostData(createdPost, originalUser));
API Benefits
This API, in it's current state, won't prevent all breakage of forum posting. The benefits exist in it's ability to be scaled to mitigate breakage during migration, as well as provide an easy-to-use/hard-to-misuse interface for developers to use.
Code Breakage Mitigation
Migrations typically lead to breaking changes. JDA is known for moving packages around between versions.
By having developers rely on our API, there won't be worry about updating code they've pushed to production. Instead, only the forum posting API would need to be updated. It would reduce the worry about introducing forum-based features into the server.
var id = ...;
var title = ...;
MessageCreateData messageData = ...;
ForumPoster.using(jda).createPost(id, title, messageData);
Details such as ForumChannel, ForumPostAction, etc.. are hidden from the user. If JDA decides to move them, any code involved in making forum posts would not have to be updated - only the API responsible for forum posts.
Im generally against investing time into making functionality more modular and abstract as long as there arent multiple users.
Like, this functionality is currently only used and needed by a single part in the code and chances are that this might potentially stay like that for a few more years. So if we now invest time into breaking this out into a sophisticated extra-API because we envision potential multiple use-cases "in the future", we make the code harder to maintain for today.
That said, this part of the API sounds useful to break out. But I would probably still wait with it until there are multiple users.
Im generally against investing time into making functionality more modular and abstract as long as there arent multiple users.
I edited the issue to include "API Benefits", if that has any impact. The implementation is extremely lightweight too: 1 class, 50 lines of code. Has some heavy foundation to it though, if it was ever decided to improve the API.
This idea actually rose from a problem mentioned by @SquidXTV in the discord:
I dont think that feature has support for forum channels
Noticed transferring questions supported forum posting. It's currently the only system that seems to use it. But the code is encapsulated within that system. Having lack of an easy-to-use forum system seems to hinder options - choices are being made based on "it's not supported". This aims at targeting support for forums, which are a great server tool
Like, this functionality is currently only used and needed by a single part in the code and chances are that this might potentially stay like that for a few more years.
I don't think it would be years before new ways to make productive use of forums come to light. Not having the option seems like it could nerf those ideas, kill them before they had a chance to live, due to "it's not supported"
So if we now invest time into breaking this out into a sophisticated extra-API because we envision potential multiple use-cases "in the future", we make the code harder to maintain for today.
It's a few lines of code that opens the door to forums. That's it, doesn't have to be a sophisticated API. The implementation I have is extremely lightweight. It can be scaled to become a sturdy API, but right now, it's just aimed at opening the door to better support for forum posting within TJ Bot
That said, this part of the API sounds useful to break out. But I would probably still wait with it until there are multiple users.
I'm hoping this will bring more users to include it in their idea making. "It's not supported", "If someone wants to do it, sure", etc... I feel like that's been a roadblock for a few things. A user mentioned "it's not supported", thought I'd get on it
- u already coded it anyways
- its indeed just a small helper api
so i dont mind 👍