Skip to content

Contributing

Jump to bottom
Ersatz edited this page Mar 8, 2023 · 1 revision

Using the organization

If you're a member of the Minecraft Commands organization, you can clone repos and manage branches directly without having to manage your own fork. This is generally considered to be the more straightforward approach to contributing.

  1. Clone: Choose the commanderbot-py repo and clone it with git clone directly, without forking it.

  2. Branch:

    • The default/base branch main is protected and, unless you're a maintainer, you will not be able to push to it. Instead, you should create and commit to a separate branch for each new extension, bug fix, or any other self-contained set of changes. This simplifies the process of alternating between different tasks and keeps your work separate from everyone else.

    • Think of a good, succinct branch name. We'll use my-branch-name as an example here. You can create and checkout a new branch at the same time with git checkout -b my-branch-name.

  3. Make changes:

    • During development you should try to separate your commits with meaningful commit messages. If you can't summarize your commit in 50-70 characters, you might want to try splitting it up into smaller, incremental pieces. This encourages a meaningful commit history, helps your future self remember what you did, and reduces the impact of merge conflicts.

    • You should update the changelog to reflect any user, API, or otherwise significant changes in your branch. This will be required as part of your pull request, but it is recommended to do this regularly for your own reference. All projects using a changelog adhere to the Keep a Changelog format. You can refer to the existing changelogs to familiarize yourself with the format.

  4. Merge: At some point you may need to merge main into your branch by running git merge main in your own branch. If someone else has committed changes to files that you have also changed in your branch, it is possible you will need to resolve merge conflicts. The main branch is generally updated with each release and high-traffic files like changelogs often conflict.

  5. Push: Push your changes with git push. If this is the first time you're pushing changes to this branch, git should prompt you to explicitly create the remote branch with git push -u origin my-branch-name.

  6. Pull request: When you're ready to contribute your changes, you can submit a pull request against the main branch to be included in the next release.

Using your own fork

If you're not a member of the Minecraft Commands organization, or you prefer to manage your own repository, you can use a fork to contribute. You will want to configure an upstream remote so that you can sync your fork with the upstream repository. The rest of the process is largely unchanged.

Software stack

All projects use:

VSCode setup

Install Poetry

Install Poetry and familiarize yourself with the commands. Poetry makes it easier to manage dependencies and keep them synchronized with everyone else.

Clone the repo

Fork and clone the commanderbot-py repo:

git clone git@github.com:MinecraftCommands/commanderbot-py.git

Create a virtual environment

You can use Poetry to create and manage a virtual environment (venv) for you, or you can do so manually.

If you wish to do so manually, the recommended approach is to create a Python virtual environment in the root of the repo:

python -m venv venv/commanderbot-py

You can use any path for the venv, but it is recommended to use venv/commanderbot-py because:

  1. everything under venv is already git-ignored; and
  2. the sub-folder commanderbot-py labels the venv to help distinguish it from others.

Install dependencies

Activate the venv you just created (such as by opening a new integrated terminal) and install dependencies:

poetry install

Once the packages are installed, you can verify the results:

poetry show

Set the Python path

Create .vscode/settings.json and set python.pythonPath to the venv you just created. The path differs based on the name you chose, and whether you're on Windows or Linux. Here's what it might look like on Linux for the commanderbot-py repo:

{
  "python.pythonPath": "venv/commanderbot-py/bin/python"
}

Configure project settings

It is important to configure certain project-level settings such as which code formatter to use. All Python projects use the black formatter. You can do this either in the folder settings at .vscode/settings.json or your workspace settings, by adding these options:

{
  "python.formatting.provider": "black"
}

Note that black itself is configured separately in pyproject.toml as part of version control.

Here are some additional recommend settings to help streamline the development process:

{
  "editor.rulers": [88],
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "files.exclude": {
    ".pytest_cache/**": true,
    "**/__pycache__": true,
    "venv/**": true,
    "*.egg-info/**": true
  }
}

Placing these options in your workspace settings will apply them to all folders in the current workspace, which is useful if you have multiple repos present.

You can access your workspace settings by opening the command palette with ctrl + shift + p and searching for Preferences: Open Workspace Settings (JSON). Make sure to place settings under the settings field, separate from folders.

Setup an instance of the bot

See the CommanderBot readme for how to configure and run an instance of the bot.

Note that the two files bot.json and bot.token as well as the entire data folder are already git-ignored, however you may choose to maintain your bot's state elsewhere.

Create launch configuration

Create .vscode/launch.json to define launch/debug configuration for the bot. Here's a starting template that sets the working directory to the git-ignored bot folder, and reads configuration from bot.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "CommanderBot",
      "type": "python",
      "request": "launch",
      "module": "commanderbot",
      "console": "integratedTerminal",
      "cwd": "${workspaceFolder}/bot",
      "args": ["bot.json", "--log", "INFO"]
    }
  ]
}

You will also need to provide a bot token to log-in with. One option is to create a .env file under the same git-ignored bot folder, and use it to set the BOT_TOKEN environment variable:

BOT_TOKEN=put_your_bot_token_here
Clone this wiki locally