FredBoat is built using Maven, so you should just be able to import the project in your favorite IDE and download all dependencies while building. Check out the issues to find out what needs to be done.
When submitting a pull request, please submit against the development branch, or you will have to reopen your PR.
Code is indented with 4 spaces and without brackets on newlines. Please use the logging system (SLF4J) instead of System.out or System.err.
It is a good practice to make use of the default code formatter of your IDE to adhere to existing conventions of the project.
- Beginner Means that the issue should be suitable for new contributors.
- Intermediate Means that the issue might be somewhat more difficult.
- Advanced Means that the could be a major feature or requires a deep understanding of the bot.
- Docs Means that help is wanted to improve the documentation.
These 4 tags all imply that help is wanted, so feel free to contribute at whichever level. Please announce your intention to work on something so we don't accidentally try to write the same changes!
Also feel free to work on your own ideas. Especially commands, we can't have too many of those.
The easiest way to write a new command for FredBoat from scratch is by having a look at how similar commands are written. A few core concepts are used by almost every command:
A FredBoat command must extend the abstract class Command.java and implement the the methods of the ICommand interface.
FredBoat runs its own, simplified permission system that takes care of properly interacting with the user. Existing permission levels are defined in PermissionLevel.java, and by implementing ICommandRestricted.java you gain access to a method to provide the minimum required permissions for your command.
Each command is provided a CommandContext during execution. This context provides access to the invoker, guild, textchannel, message, parsed arguments etc. Further more it provides convenience methods to reply to users.
Each command is required to provide a proper help string explaining all possible usages and arguments. If your command gets too complex for that, adding an additional page to the official documentation (example: Permissions commands may be discussed.
Commands intended for public use (read: non-admin, non-maintenance commands) are required to support translation.
See Translations for more details on our flow of adding new strings to translation files.
You can access translations through any provided Context.
The ShuffleCommand.java makes use of permissions by implementing ICommandRestricted and overriding getMinimumPerms() to return a DJ level, making this command only executable by users with the DJ level or higher. It uses the CommandContext to know which guild the command is run in and access that guild's player. Being a public command, it uses translated strings in its replies and its help.
Click me
public class ShuffleCommand extends Command implements IMusicCommand, ICommandRestricted {
@Override
public void onInvoke(@Nonnull CommandContext context) {
GuildPlayer player = PlayerRegistry.get(context.guild);
player.setShuffle(!player.isShuffle());
if (player.isShuffle()) {
context.reply(context.i18n("shuffleOn"));
} else {
context.reply(context.i18n("shuffleOff"));
}
}
@Nonnull
@Override
public String help(@Nonnull Context context) {
return "{0}{1}\n#" + context.i18n("helpShuffleCommand");
}
@Override
public PermissionLevel getMinimumPerms() {
return PermissionLevel.DJ;
}
}If you just want to fix existing translations, you are welcome to contribute over at FredBoat's Crowdin project.
Adding new translation strings to FredBoat requires the following steps:
- Check out the FredBoat translation repo
- Edit the
en_US.properties, and only that file. Make sure to keep your style as close as possible to the existing strings and place new strings at the topically appropriate place - Open a PR to the FredBoat translation repo with your edits/additions to the
en_US.propertiesfile. - If you are writing a PR for FredBoat, that relies on the new strings, you will have to await a successful review of both PRs. A collaborateur will then import your new strings into crowdin, make a build, and update the translation repo. After that has happened, your FredBoat PR will need to point to the new head commit of the translation project, and will then be merged.
- present tense, imperative verbs
- group strings topically, for example help strings belong next to each other in the file
- keep formatting characters (_ * ` etc) out of the translations files, they should be added by the code instead
- don't overuse variables, as those make it harder to write good translations
Obtaining a well functioning and productive setup of the IDE may be an intimidating process, especially for users new to coding or the Java world. Here are some tips that will hopefully make this step a bit easier.
Add credentials.yaml and config.yaml files to the FredBoat root directory.
To run the FredBoat bot in IntelliJ IDEA, find the little green play button in the main class FredBoat.java and start it from there:
Click me
This also allows you to take advantage of Java hotswapping, which you can enable in IDEA like so:
Click me
Reloading while the bot is running will have your changes hot swapped, so there is no need to fully restart it each time when you are rapidly testing out a lot of small changes.
Click me
Reformatting your code, organizing imports, recompiling, etc are tasks that you may end up running a lot each day.
A convenient time to do them is when saving files, so you might want to create a macro that does all the housekeeping for you and put it on the CTRL + S hotkey, or use a plugin like Save Actions.
Here is a decent configuration:
Click me
Are you planning to contribute and have burning questions not answered here? Please be invited to join FredBoat Hangout and request an admin for writing access to the #coding channel.